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Introduction 

CP/M is a monitor control program for microcomputer system develop- 
ment which uses IBM-compatible flexible disks for backup storage* Using a 
computer mainframe based upon Intel's 8080 microcomputer, CP/M 
provides a general environment for program construction, storage, and 
editing, along with assembly and program check-out facilities. An important 
feature of CP/M is that it can be easily altered to execute with any computer 
configuration which uses an Intel 8080 (or Zilog Z-80) Central Processing 
Unit, and has at least 16K bytes of main memory with up to four IBM- 
compatible diskette drives. Although the standard Digital Research ver- 
sion operates on a single-density Intel MDS 800, several different hard- 
ware manufacturers support their own input-output drivers for CP/M. 

The CP/M monitor provides rapid access to programs through a com- 
prehensive file management package. The file subsystem supports a named 
file structure, allowing dynamic allocation of file space as well as sequential 
and random file access. Using this file system, a large number of distinct 
programs can be stored in both source and machine executable form. 

CP/M also supports a powerful context editor, Intel-compatible assembler, 
and debugger subsystem. Optional software includes a powerful Intel- 
compatible macro assembler, symbolic debugger, along with various 
high-level languages. When coupled with CP/M's Console Command 
Processor, the resulting facilities equal or excel similar large computer 
facilities. 

CP/M is logically divided into several distinct parts: 

BIOS Basic I/O System (hardware dependent) 

BDOS Basic Disk Operating System 

CCP Console Command Processor 

TPA Transient Program Area 

The BIOS provides the primitive operations necessary to access the diskette 
drives and to interface standard peripherals (teletype, CRT, Paper Tape 
Reader/Punch, and user-defined peripherals), and can be tailored by the 
user for any particular hardware environment by "patching" this portion of 
CP/M. 

The BDOS provides disk management by con trolling one or more disk drives 
containing independent file directories. The BDOS implements disk 
allocation strategies which provide fully dynamic file construction while 



minimizing head movement across the disk during access. Any particular file 
may contain any number of records, not exceeding the size of any single disk. 
In a standard CP/M system, each disk can contain up to 64 distinct files. The 
BDOS has entry points which include the following primitive operations 
which can be programmatically accessed: 

SEARCH Look for a particular disk file by name. 

OPEN Open a file for further operations. 

CLOSE Close a file after processing. 

RENAME Change the name of a particular file. 

READ Read a record from a particular file. 

WRITE Write a record onto the disk. 

SELECT Select a particular disk drive for further operations. 

The CCP provides symbolic interface between the user's console and the 
remainder of the CP/M system. The CCP reads the console device and 
processes commands which include listing the file directory, printing the 
contents of files, and controlUng the operation of transient programs, such 
as assemblers, editors, and debuggers. The standard commands which are 
available in the CCP are listed in a following section. 

The last segment of CP/M is the area called the Ti-ansient Program Area 
(TPA). The TPA holds programs which are loaded from the disk under 
command of the CCP. During program editing, for example, the TPA holds 
the CP/M text editor machine code and data areas. Similarly, programs 
created under CP/M can be checked out by loading and executing these 
programs in the TPA. 

It should be mentioned that any or all of the CP/M component subsystems 
can be "overlayed" by an executing program. That is, once a user's program 
is loaded into the TPA, the CCP, BDOS, and BIOS areas can be used as the 
program's data area. A "bootstrap" loader is programmatically accessible 
whenever the BIOS portion is not overlay ed; thus, the user program need 
only branch to the bootstrap loader at the end of execution, and the complete 
CP/M monitor is reloaded from disk. 



It should be reiterated that the CP/M operating system is partitioned into 
distinct modules, including the BIOS portion which defines the hardware 
environment in which CP/M is executing. Thus, the standard system can be 



easily modified to any non-standard environment by changing the 
peripheral drivers to handle the custom system. 

An Overview of CP/M 2.0 Facilities 

CP/M 2.0 is a high-performance single-console operating system which uses 
table driven techniques to allow field configuration to match a wide variety 
of disk capacities. All of the fundamental file restrictions are removed, while 
maintaining upward compatibility from previous versions of release 1. 
Features of CP/M 2.0 include field specification of one to sixteen logical 
drives, each containing up to eight megabytes. Any particular file can reach 
the full drive size with the capability to expand to thirty-two megabytes in 
future releases. The directory size can be field configured to contain any 
reasonable number of entries, and each file is optionally tagged with 
read/only and system attributes. Users of CP/M 2.0 are physically separated 
by user numbers, with faciUties for file copy operations from one user area to 
another. Powerful relative-record random access functions are present in 
CP/M 2.0 which provide direct access to any of the 65536 records of an eight 
megabyte file. 

All disk-dependent portions of CP/M 2.0 are placed into a BIOS-resident 
"disk parameter block" which is either hand coded or produced automat- 
ically using the disk definition macro library provided with CP/M 2.0. The 
end user need only specify the maximum number of active disks, the starting 
and ending sector numbers, the data allocation size, the maximum extent of 
the logical disk, directory size information, and reserved track values. The 
macros use this information to generate the appropriate tables and table 
references for use during CP/M 2.0 operation. Deblocking information is also 
provided which aids in assembly or disassembly of sector sizes which are 
multiples of the fundamental 128 byte data unit, and the system alteration 
manual includes general-purpose subroutines which use this deblocking 
information to take advantage of larger sector sizes. Use of these 
subroutines, together with the table driven data access algorithms, make 
CP/M 2.0 truly a universal data management system. 

File expansion is achieved by providing up to 512 logical file extents, where 
each logical extent contains 16K bytes of data. CP/M 2.0 is structured, 
however, so that as much as 128K bytes of data is addressed by a single 
physical extent (corresponding to a single directory entry), thus maintaining 
compatibility with previous versions while taking full advantage of directory 
space. 

Random access facilities are present in CP/M 2.0 which allow immediate 
reference to any record of an eight megabyte file. Using CP/M's unique data 
organization, data blocks are only allocated when actually required and 
movement to a record position requires little search time. Sequential file 
access is upwardly compatible from earlier versions to the full eight 



megabytes, while random access compatibility stops at 512K byte files. Due 
to CP/M 2.0's simpler and faster random access, application programmers 
are encouraged to alter their programs to take full advantage of the 2.0 
facilities. 

Several CP/M 2.0 modules and utilities have improvements which 
correspond to the enhanced file system. STAT and PIP both account for file 
attributes and user areas, while the CCP provides a "login" function to 
change from one user area to another. The CCP also formats directory 
displays in a more convenient manner and accounts for both CRT and 
hard'Copy devices in its enhanced line editing functions. 

Functional Description of CP/M 

The user interacts with CP/M primarily through the CCP, which reads and 
interprets commands entered through the console. In general, the CCP 
addresses one of several disks which are online (the standard system 
addresses up to four different disk drives). These disk drives are labelled A, 
B, C, and D. A disk is "logged in" if the CCP is currently addressing the disk. 
In order to clearly indicate which disk is the currently logged disk, the CCP 
always prompts the operator with the disk name followed by the symbol " > " 
indicating that the CCP is ready for another command. Upon initial start up, 
the CP/M system is brought in from disk A, and the CCP displays the 
message 

xxK CP/M VER m.m 

where xx is the memory size (in kilobytes) which this CP/M system manages, 
and m.m is the CP/M version number. All CP/M systems are initially set to 
operate in a 16K memory space, but can be easily reconfigured to fit any 
memory size on the host system. Following system signon, CP/M automat- 
ically logs in disk A, prompts the user with the symbol "A> " (indicating that 
CP/M is currently addressing disk "A"), and waits for a command. The 
commands are implemented at two levels: built-in commands and transient 
commands. 



General Command Structure 

Built-in commands are a part of the CCP program itself, while transient 
commands are loaded into the TPA from disk and executed. The built-in 
commands are 

ERA Erase specified files. 

DIR Displays file names in the directory. 
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REN Rename the specified file. 

SAVE Save memory contents in a file. 

TYPE Type the contents of a file on the logged disk. 

USER Move to another area within the same directory. 

Nearly all of the commands reference a particular file or group of files. The 
form of a file reference is specified below. 

File References 

A file reference identifies a particular file or group of files on a particular disk 
attached to CP/M. These file references can be either "unambiguous" (ufn) 
or "ambiguous" (afn). An unambiguous file reference uniquely identifies a 
single file, while an ambiguous file reference may be satisfied by a number of 
different files. 

File references consist of two parts: the primary name and the secondary 
name. Although the secondary name is optional, it usually is generic; that is, 
the secondary name "ASM" for example, is used to denote that the file is an 
assembly language source file, while the primary name distinguishes each 
particular source file. The two names are separated by a **." as shown below: 

PPPPPPPP.SSS 

where pppppppp represents the primary name of eight characters or less, and 
sss is the secondary name of no more than three characters. As mentioned 
above, the name 

pppppppp 

is also allowed and is equivalent to a secondary name consisting of three 
blanks. The characters used in specifying an unambiguous file reference 
cannot contain any of the special characters 

while all alphanumerics and remaining special characters are allowed. 

An ambiguous file reference is used for directory search and pattern 
matching. The form of an ambiguous file reference is similar to an 
unambiguous reference, except the symbol **?" may be interspersed 
throughout the primary and secondary names. In various commands 
throughout CP/M, the "?" symbol matches any character of a file name in 
the "?" position. Thus, the ambiguous reference 



X?Z.C?M 

is satisfied by the unambiguous file names 

XYZ.COM 
and 

X3Z.CAM 
Note that the ambiguous reference 

is equivalent to the ambiguous file reference 

????????.??? 

while 

pppppppp.* 
and 

*.sss 

are abbreviations for 

pppppppp.??? 
and 

????????.sss 

respectively. As an example, 

DIR *.* 

is interpreted by the CCP as a command to list the names of all disk files in 
the directory, while 

DIRX.Y 
searches only for a file by the name X.Y. Similarly, the command 

DIR X?Y.C?M 

causes a search for all (unambiguous) file names on the disk which satisfy this 
ambiguous reference. 



The following file names are valid unambiguous file references: 

X XYZ GAMMA 

X.Y XYZ.COM GAMMA.l 

As an added convenience, the programmer can generally specify the disk 
drive name along with the file name. In this case, the drive name is given as 
a letter A through Z followed by a colon ( : ). The specified drive is then "logged 
in** before the file operation occurs. Thus, the following are valid file names 
with disk name prefixes: 

A:X.Y B:XYZ CiGAMMA 

Z:XYZ.COM B:X.A?M C:*.ASM 

It should also be noted that all alphabetic lower case letters in file and drive 
names are always translated to upper case when they are processed by the 
OCR 

Switching Disks 

The operator can switch the currently logged disk by typing the disk drive 
name (A, B, C, or D) followed by a colon (:) when the CCP is waiting for 
console input. Thus, the sequence of prompts and commands shown below 
might occur after the CP/M system is loaded from disk A: 

16K CP/M VER 2.0 

A>DIR List all files on disk A. 

SAMPLE ASM 

SAMPLE PRN 

A>B: Switch to disk B, 

B>Dir *.ASM List all "ASM** files on B. 

DUMP ASM 

FILES ASM 

B>A: Switch back to A. 

Form of Built-in Commands 

The file and device reference forms described above can now be used to fully 
specify the structure of the built-in commands. In the description below, 
assume the following abbreviations: 

ufn unambiguous file reference 

afn ambiguous file reference 

cr carriage return 

Further, recall that the CCP always translates lower case characters to 
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upper case characters internally. Thus, lower case alphabetics are treated as 
if they are upper case in command names and file references. 

ERAse Command 

ERA afn 

The ERA (erase) command removes files from the currently logged-in disk 
(i.e., the disk name currently prompted by CP/M preceding the **>"). The 
files which are erased are those which satisfy the ambiguous file reference 
afn. The following examples illustrate the use of ERA: 

ERA X. Y The file named X. Y on the currently logged disk 

is removed from the disk directory, and the space 
is returned. 

ERA X.* All files with primary name X are removed from 

the current disk. 

ERA *.ASM All files with secondary name ASM are removed 

from the current disk. 

ERA X?Y.C?M All files on the current disk which satisfy the 

ambiguous reference X?Y.C?M are deleted. 

ERA *. * Erase all files in the current user's directory. (See 

USER n, page 13.) The CCP prompts with the 
message 

ALL(Y/N)? 
which requires a Y response before files are 
actually removed. 

ERA B: *.PRN All files on drive B which satisfy the ambiguous 

reference ????????.PRN are deleted, indepen- 
dently of the currently logged disk. 

DIRectory Command 

DIR afn 

The DIR (directory) command causes the names of all files which satisfy the 
ambiguous file name afn to be listed at the console device. As a special case, 
the command 

DIR 

lists the files on the currently logged disk ( the command "DIR" is equivalent 
to the command "DIR *.*"). Valid DIR commands are shown below. 
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DIR X.Y 

DIR X?Z.C?M 

DIR ??.Y 

Similar to other CCP commands, the afn can be preceded by a drive name. 
The following DIR commands cause the selected drive to be addressed before 
the directory search takes place. 

DIRB: 

DIRB:X.Y 

DIRB:*.A?M 

If no files can be found on the selected diskette which satisfy the directory 
request, then the message "NOT FOUND" is typed at the console. 

REName Command 

REN ufnl = ufn2 

The REN (rename) command allows the user to change the names of files on 
disk. The file satisfying ufn2 is changed to ufnl. The currently logged disk is 
assumed to contain the file to rename (ufnl). The CCP also allows the user 
to type a left-directed arrow instead of the equal sign, if the user's console 
supports this graphic character. Examples of the REN command are 

REN X.Y = Q.R The file Q.R is changed to X.Y. 

REN XYZ.COM = XYZ.XXX The file XYZ.XXX is changed to 

XYZ.COM. 

The operator can precede either ufnl or ufn2 (or both) by an optional drive 
address. Given that ufnl is preceded by a drive name, then ufn2 is assumed 
to exist on the same drive as ufnl. Similarly, if ufn2 is preceded by a drive 
name, then ufnl is assumed to reside on that drive as well. If both ufnl and 
ufn2 are preceded by drive names, then the same drive must be specified in 
both cases. The following REN commands illustrate this format, 

REN A:X.ASM = YASM The file Y.ASM is changed to X.ASM 

on drive A. 

RENB:ZARBAS = ZOTBAS The file ZOT.BAS is changed to 

ZARBAS on drive B. 
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REN B:A.ASM = B:A.BAK The file A.BAK is renamed to A.ASM 

on drive B. 

If the file ufnl is already present, the REN command will respond with the 
error "FILE EXISTS" and not perform the change. If ufn2 does not exist on 
the specified diskette, then the message "NOT FOUND" is printed at the 
console. 

SAVE Command 

SAVE n ufn 

The SAVE command places n pages (256-byte blocks) onto disk from the 
TPA and names this file ufn. In the CP/M distribution system, the TPA 
starts at lOOH (hexadecimal), which is the second page of memory. Thus, if 
the user's program occupies the area from lOOH through 2FFH, the SAVE 
command must specify two pages of memory. The machine code file can be 
subsequently loaded and executed. Examples are: 

SAVE 3 X.COM Copies lOOH through 3FFH to 

X.COM. 

SAVE 40 Q Copies lOOH through 28FFH to Q 

(note that 28 is the page count in 
28FFH, and that 28H = 2*16 + 8 = 
40 decimal). 

SAVE 4 X.Y Copies lOOH through 4FFH to X.Y. 

The SAVE command can also specify a disk drive in the afn portion of the 
command, as shown below. 

SAVE 10 B:ZOTCOM Copies 10 pages (lOOH through 

OAFFH) to the file Z0T.COM on 
drive B. 

The SAVE operation can be used any number of times without altering the 
memory image. 

TYPE Command 

TYPE ufn 

The TYPE command displays the contents of the ASCII source file ufn on 
the currently logged disk at the console device. Valid TYPE commands are 

TYPE X.Y 
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TYPE X.PLM 
TYPE XXX 

The TYPE command expands tabs (clt-I characters), assuming tab 
positions are set at every eighth column. The ufn can also reference a drive 
name as shown below. 

TYPE BrX.PRN The file X.PRN from drive B is displayed. 

USER Command 

USERn 
Where n is an integer value in the range to 15. 

Upon cold start, the operator is automatically *'logged" into user area 
number 0. The operator may issue the USER command at any time to move 
to another logical area within the same directory. 

Drives which are logged in while addressing one user number are automat- 
ically active when the operator moves to another user number since a user 
number is simply a prefix which accesses particular directory entries on the 
active disks. 

The active user number is maintained until changed by a subsequent USER 
command, or until a cold start operation when user is again assumed. 

Line Editing and Output Control 

The CCP allows certain Hne editing functions while typing command lines. 
"Control*' indicates that the Control key and the indicated key are to be 
pressed simultaneously. CCP commands can generally be up to 255 
characters in length; they are not acted upon until the carriage return key 
is pressed. 

rubout/delete Remove and echo last character typed 

Control C Reboot CP/M when at beginning of line 

Control E Physical end of line: carriage is returned, but line 

is not sent until the carriage return key is 
depressed. 
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Control H 



Control J 
Control M 
Control R 
Control X 



Backspace one character position. Produces the 
backspace overwrite function. Can be changed 
internally to another character, such as delete, 
through a simple single byte change. 

Line feed. Terminates current input. 
Carriage return. Terminates input. 
Retype current command Hne after new line. 
Backspace to beginning of current line. 



The line editor keeps track of the current prompt column position so that the 
operator can properly align data input following a Control R or Control X 
command. 

The control functions Control P and Control S affect console output as 
shown below. 

Control P Copy all subsequent console output to the 

currently assigned list device (see the STAT 
command). Output is sent to both the Ust device 
and the console device until the next Control P is 
typed. 

Control S Stop the console output temporarily. Program 

execution and output continue when the next 
character is typed at the console (e.g., another 
Control S). This feature is used to stop output on 
high speed consoles, such as CRT's, in order to 
view a segment of output before continuing. 

Transient Commands 

Transient commands are loaded from the currently logged disk and executed 
in the TPA. The transient commands defined for execution under the CCP 
are shown below. Additional functions can easily be defined by the user (see 
the LOAD command definition). 



STAT 



ASM 



List the number of bytes of storage remaining on 
the currently logged disk, provide statistical 
information about particular files, and display or 
alter device assignment. 

Load the CP/M assembler and assemble the 
specified program from disk. 
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LOAD Load the fUe in Intel "hex" machine code format 

and produce a file in machine executable form 
which can be loaded into the TPA (this loaded 
program becomes a new command under the 
CCP). 

DDT Load the CP/M debugger into TPA and start 

execution. 

PIP Load the Peripheral Interchange Program for 

subsequent disk file and peripheral transfer 
operations. 

ED Load and execute the CP/M text editor program. 

SUBMIT Submit a file of commands for batch processing. 

XSUB Allow submitted commands to receive input 

from the submit file, 

DUMP Dump the contents of a file in hex. 

Transient conmiands are specified in the same manner as built-in commands, 
and additional commands can be easily defined by the user. As an added 
convenience, the transient command can be preceded by a drive name, 
which causes the transient to be loaded from the specified drive into the 
TPA for execution. Thus, the command 

B:STAT 

causes CP/M to temporarily "log in" drive B for the source of the STAT 
transient, and then return to the original logged disk for subsequent 
processing. 

The basic transient commands are listed in detail below. 

STAT 

The STAT command provides general statistical information about file 
storage and device assignment. It is initiated by typing one of the 
following forms: 

STAT 

STAT "command Une" 

Special forms of the "command line" allow the current device assignment 
to be examined and altered as well. The various command Unes which can 
be specified are shown below, with an explanation of each form shown to 
the right. 
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STAT <er> 



If the user types an empty command line, the 
STAT transient calculates the storage remaining 
on all active drives, and prints a message 



or 



x: R/W, SPACE: nnnK 
x: R/0, SPACE: nnnK 



for each active drive x, where R/W indicates the 
drive may be read or written, and R/0 indicates 
the drive is read only (a drive becomes R/0 by 
exphcitly setting it to read only, as shown below, 
or by inadvertently changing diskettes without 
performing a warm start). The space remaining 
on the diskette in drive x is given in kilobytes by 
nnn. 



STAT x: <cr> 



If a drive name is given, then the drive is selected 
before the storage is computed. Thus, the com- 
mand "STAT B:" could be issued while logged 
into drive A, resulting in the message 



STATafn<cr> 



BYTES REMAINING ON B: nnnK 

The command line can also specify a set of files to 
be scanned by STAT The files which satisfy afn 
are listed in alphabetical order, with storage 
requirements for each file under the heading 



RECS BYTS EX 
rrrr bbbK ee 



D:FILENAME.TYP 
d:pppppppp.sss 



where rrrr is the number of 128-byte records 
allocated to the file, bbb is the number of 
kilobytes allocated to the file 
(bbb = rrrr*128/1024), ee is the number of 16K 
extensions (ee = bbb/16), d is the drive name 
containing the file ( A...Z ), pppppppp is the (up to) 
eight-character primary file name, and sss is the 
(up to) three-character secondary name. After 
listing the individual files, the storage usage is 
summarized. 



STATx:afn<cr> 



As a convenience, the drive name can be given 
ahead of the afn. In this case, the specified drive 
is first selected, and the form "STAT afn" is 
executed. 
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STAT difilename.typ $S <cr> 



("d:'* is optional drive 
name and **filename,typ" 
is an unambiguous or 
ambiguous file name) 



Produces the output display format: 
Size Recs Bytes Ext Ace 
48 48 6K 1 R/OA:ED.COM 
55 55 12K 1 R/0 (ArPIP.COM) 
65536 128 2K 2 R/WA:X.DAT 
The $S parameter causes the *'Size" field to be 
displayed. (The command may be used without 
the $S if desired,) The Size field lists the virtual 
file size in records, while the "Recs" field sums the 
number of virtual records in each extent. For files 
constructed sequentially, the Size and Recs 
fields are identical. The "Bytes" field lists the 
actual number of bytes allocated to the corre- 
sponding file. The minimum allocation unit is 
determined at configuration time, and thus the 
number of bytes corresponds to the record count 
plus the remaining unused space in the last 
allocated block for sequential files. Random 
access files are given data areas only when 
written, so the Bytes field contains the only 
accurate allocation figure. In the case of random 
access, the Size field gives the logical end-of-file 
record position and the Recs field counts the 
logical records of each extent (each of these 
extents, however, may contain unallocated 
"holes" even though they are added into the 
record count). The **Ext" field counts the 
number of local 16K extents allocated to the file. 
The "Ace" field gives the R/0 or R/W access 
mode, which is changed using the commands 
shown below. The parentheses shown around the 
PIP.COM file name indicate that it has the 
"system" indicator set, so that it will not be listed 
in DIR commands. 



STAT drfilename.typ $R/0 <cr> 

Places the file or set of files in a read-only status 
until changed by a subsequent STAT command. 
The R/0 status is recorded in the directory with 
the file so that it remains R/0 through inter- 
vening cold start operations. When a file is 
marked R/0, attempts to erase or write into the 
file result in a terminal BDOS message: Bdos Err 
on D: File R/0. 

STAT d:filename.typ $R/W <cr) 

Places the file in a permanent read /write status. 
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STAT d:filename.typ $S /S <cr> 

Attaches the system indicator to the file. 

STAT drfilename.typ $DIR (cr> 

Removes the system indicator from the file. 



STATd:DSK:(cr> 



Lists the drive characteristics of the disk named 
by "d:" which is in the range A:, B:, ..., P:. The 
drive characteristics are hsted in the format: 
d: Drive Characteristics 
65536: 128 Byte Record Capacity 
8192: Kilobyte Drive Capacity 
128: 32 Byte Directory Entries 
0: Checked Directory Entries 
1024: Records/ Extent 
128: Records/Block 
58: Sectors/Track 
2: Reserved Tracks 
The total record capacity is listed, followed by 
the total drive capacity listed in Kbytes. The 
number of checked entries is usually identical to 
the directory size for removable media, since this 
mechanism is used to detect changed media 
during CP/M operation without an intervening 
warm start. The number of records per extent 
determines the addressing capacity of each 
directory entry (1024 times 128 bytes, or 128K in 
the example above). The number of records per 
block shows the basic allocation size (in the 
example, 128 records/block times 128 bytes per 
record, or 16K bytes per block). The Ustingis then 
followed by the number of physical sectors per 
track and the number of reserved tracks. 



STAT DSK: <cr> 
STATUSR:<cr> 



Lists drive characteristics as above for all 
currently active drives. 

Produces a list of the user numbers which have 
files on the currently addressed disk. The display 
format is: 

Active User : 

Active Files: 1 3 
where the first Une lists the currently addressed 
user number, as set by the last CCP USER 
command, followed by a list of user numbers 
scanned from the current directory. In the above 
case, the active user number is (default at cold 
start), with three user numbers which have 
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active files on the current disk. The operator can 
subsequently examine the directories of the 
other user numbers by logging in with USER 1, 
USER 2, or USER 3 commands, followed by a 
DIR command at the CCP level. 

The STAT command also allows control over the physical to logical device 
assignment (see the lOBYTE function described in the "CP/M Interface 
Guide." In general, there are four logical peripheral devices which are, at any 
particular instant, each assigned to one of several physical peripheral 
devices. The four logical devices are named: 

CON: The system console device (used by CCP for 

communication with the operator) 

RDR: The paper tape reader device 

PUN: The paper tape punch device 

LST: The output list device 

The actual devices attached to any particular computer system are driven by 
subroutines in the BIOS portion of CP/M. Thus, the logical RDR: device, for 
example, could actually be a high speed reader, Teletype reader, or cassette 
tape. In order to allow some flexibility in device naming and assignment, 
several physical devices are defined, as shown below: 

TTY: Teletype device (slow speed console) 

CRT: Cathode ray tube device (high speed console) 

BAT: Batch processing (console is current RDR:, 

output goes to current LST: device) 

UCl: User-defined console 

PTR: Paper tape reader (high speed reader) 

URl: User-defined reader #1 

UR2: User-defined reader #2 

PTP: Paper tape punch (high speed punch) 

UPl: User-defined punch #1 
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UP2: User-defined punch # 2 

LPT: Line printer 

ULl: User-defined list device #1 

It must be emphasized that the physical device names may or may not 
actually correspond to devices which the names imply. That is, the FTP: 
device may be implemented as a cassette write operation, if the user wishes. 
The exact correspondence and driving subroutine is defined in the BIOS 
portion of CP/M. In the standard distribution version of CP/M, these 
devices correspond to their names on the MDS 800 development system. 

The command: 

STAT VAL: <cr> 

produces a summary of the available status commands, resulting in the 
output: 

Temp R/0 Disk: d: = R/0 

Set Indicator: d:filename.typ$R/0 $R/W $SYS $DIR 

Disk Status: DSK: d:DSK: 

User Status: USR: 

lobyte Assign: 

CON. = TTY: CRT: BAT: UCl 

RDR: = TTY: PTR: URl: UR2 

PUN: = TTY: PTP: UPl: UP2 

LST: = TTY: CRT: LPT: ULl 

In each case, the logical device shown to the left can take any of the four 
physical assignments shown to the right on each line. The current logical to 
physical mapping is displayed by typing the command 



STATDEV:<cr> 







which produces a listing of each logical device to the left, and the current 
corresponding physical device to the right. For example, the list might 
appear as follows: 
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CON: = CRT 
RDR: = URl 
PUN: = PTP 
LST: = TTY 

The current logical to physical device assignment can be changed by typing 
a STAT command of the form 

STAT Idl = pdl, ld2 = pd2 , ... , Idn = pdn <cr> 

where Idl through Idn are logical device names, and pdl through pdn are 
compatible physical device names (i.e., Idi and pdi appear on the same line in 
the "VAL:*' command shown above). The following are valid STAT 
commands which change the current logical to physical device assignments: 

STAT CON: = CRT: <cr> 

STAT PUN: = TTY:,LST: = LPT:, RDR: = TTY: <cr> 



ASMufh 

The ASM command loads and executes the CP/M 8080 assembler. The ufn 
specifies a source file containing assembly language statements where the 
secondary name is assumed to be ASM, and thus is not specified. The 
following ASM commands are valid: 

ASMX 

ASM GAMMA 

The two-pass assembler is automatically executed. If assembly errors occur 
during the second pass, the errors are printed at the console. 

The assembler produces a file 

x.PRN 

where x is the primary name specified in the ASM command. The PRN file 
contains a listing of the source program (with imbedded tab characters if 
present in the source program), along with the machine code generated for 
each statement and diagnostic error messages, if any. The PRN file can be 
listed at the console using the TYPE command, or sent to a peripheral device 
using PIP (see the PIP command structure below). Note also that the PRN 
file contains the original source program, augmented by miscellaneous 
assembly information in the leftmost 16 columns (program addresses and 
hexadecimal machine code, for example). Thus, the PRN file can serve as a 
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backup for the original source file: if the source file is accidentally removed 
or destroyed, the PRN file can be edited (see the ED operator's guide) by 
removing the leftmost 16 characters of each line (this can be done by issuing 
a single editor "macro" command). The resulting file is identical to the 
original source file and can be renamed (REN) from PRN to ASM for 
subsequent editing and assembly. The file 

x.HEX 

is also produced which contains 8080 machine language in Intel **hex" format 
suitable for subsequent loading and execution (see the LOAD command). 
For complete details of CP/M's assembly language program, see the "CP/M 
Assembler Language (ASM) User's Guide." 

Similar to other transient commands, the source file for assembly can be 
taken from an alternate disk by prefixing the assembly language file name by 
a disk drive name. Thus, the command 

ASM BiALPHA <cr> 

loads the assembler from the currently logged drive and operates upon the 
source program ALPHA. ASM on drive B. The HEX and PRN files are also 
placed on drive B in this case. 



LOAD ufh cr 

The LOAD command reads the file ufn, which is assumed to contain "hex" 
format machine code, and produces a memory image file which can be 
subsequently executed. The file name ufn is assumed to be of the form 

x.HEX 

and thus only the name x need be specified in the command. The LOAD 
command creates a file named 

x.COM 

which marks it as containing machine executable code. The file is actually 
loaded into memory and executed when the user types the file name x 
immediately after the prompting character "> " printed by the CCP. 

In general, the CCP reads the name x following the prompting character and 
looks for a built-in function name. If no function name is found, the CCP 
searches the system disk directory for a file by the name 
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x.COM 

If found, the machine code is loaded into the TPA, and the program executes. 
Thus, the user need only LOAD a hex file once; it can be subsequently 
executed any number of times by simply typing the primary name. In this 
way, the user can "invent'* new commands in the CCR (Initialized disks 
contain the transient commands as COM files, which can be deleted at the 
user's option.) The operation can take place on an alternate drive if the file 
name is prefixed by a drive name. Thus 

LOAD B:BETA 

brings the LOAD program into the TPA from the currently logged disk and 
operates upon drive B after execution begins. 

It must be noted that the BETA. HEX file must contain valid Intel format 
hexadecimal machine code records (as produced by the ASM program, for 
example) which begin at lOOH, the beginning of the TPA. Further, the 
addre$ses in the hex records must be in ascending order; gaps in unfilled 
memory regions are filled with zeroes by the LOAD command as the hex 
records are read. Thus, LOAD must be used only for creating CP/ M standard 
"COM** files which operate in the TPA. Programs which occupy regions of 
memory other than the TPA can be loaded under DDT. 



PIP 

PIP is the CP/M Peripheral Interchange Program which implements the 
basic media conversion operations necessary to load, print, punch, copy, and 
combine disk files. The PIP program is initiated by typing one of the 
following forms 

PIP <cr> 

PIP "command line" <cr> 

In both cases, PIP is loaded into the TPA and executed. In case 1, PIP reads 
command lines directly from the console, prompted with the ****' character, 
until an empty command line is typed (i.e., a single carriage return is issued 
by the operator). Each successive command line causes some media 
conversion to take place according to the rules shown below. Form 2 of the 
PIP command is equivalent to the first, except that the single command line 
given with the PIP command is automatically executed, and PIP terminates 
immediately with no further prompting of the console for input command 
lines. The form of each command line is 

destination = source #1, source #2, ... , source #n <cr) 
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where "destination** is the file or peripheral device to receive the data, and 
"source #1, ..., source #n*' represents a series of one or more files or devices 
which are copied from left to right to the destination. 

When multiple files are given in the command line (i.e., n > 1), the individual 
files are assumed to contain ASCII characters, with an assumed CP/M 
end-of-file character (ctl-Z) at the end of each file (see the parameter to 
override this assumption). The equal symbol ( = ) can be replaced by a 
left-oriented arrow, if your console supports this ASCII character, to 
improve readability. Lower case ASCII alphabetics are internally translated 
to upper case to be consistent with CP/M file and device name conventions. 
Finally, the total command line length cannot exceed 255 characters (ctl-E 
can be used to force a physical carriage return for Unes which exceed the 
console width). 



The destination and source elements can be unambiguous references to 
CP/M source files, with or without a preceding disk drive name. That is, any 
file can be referenced with a preceding drive name (A:, B:, C:, or D:) which 
defines the particular drive where the file may be obtained or stored. When 
the drive name is not included, the currently logged disk is assumed. Further, 
the destination file can also appear as one or more of the source files, in which 
case the source file is not altered until the entire concatenation is complete. 
If the destination file already exists, it is removed if the command line is 
properly formed (it is not removed if an error condition arises). The following 
command lines (with explanations to the right) are valid as input to PIP: 

X = Y (cr> Copy to file X from file Y, where X and 

Y are unambiguous file names; Y 
remains unchanged. 

X = Y, Z (cr> Concatenate files Y and Z and copy to 

file X, with Y and Z unchanged. 

X.ASM = Y.ASM,Z.ASM,FIN.ASM <cr> 

Create the file X.ASM from the con- 
catenation of the Y, Z, and FIN files 
with type ASM. 

NEW.ZOT = B:OLD.ZAP <cr> Move a copy of OLD.ZAP from drive B 

to the currently logged disk; name the 
file NEW.ZOT. 

B:A.U. = B:B.VA:C,W,D.X <cr> Concatenate file B.V from drive B with 

C.W from drive A and D.X. from the 
logged disk; create the file A.U on drive 
B. 
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For more convenient use, PIP allows abbreviated commands for transferring 
files between disk drives. The abbreviated forms are 

PIP x: = afn <cr> 

PIP x: - y:afn <cr> 

PIP ufn = y: <cr> 

PIPx:ufn = y: <cr> 

The first form copies all files from the currently logged disk which satisfy the 
afn to the same file names on drive x (x = A...Z). The second form is 
equivalent to the first, where the source for the copy is drive y (y = A...Z). The 
third form is equivalent to the command "PIP ufn = y:ufn (cr>" which 
copies the file given by ufn from drive y to the file ufn on drive x. The fourth 
form is equivalent to the third, where the source disk is explicitly given by.y. 

Note that the source and destination disks must be different in all of these 
cases. If an afn is specified, PIP lists each ufn which satisfies the afn as it is 
being copied. If a file exists by the same name as the destination file, it is 
removed upon successful completion of the copy, and replaced by the copied 
file. 

The following PIP commands give examples of valid disk-to-disk copy 
operations: 

B: = *.COM <cr> Copy all files which have the secondary name 

**COM'* to drive B from the current drive. 

A: = BiZAR* <cr> Copy all files which have the primary name 

"ZAP" to drive A from drive B. 

ZAP.ASM = B: <cr> Equivalent to ZARASM = BrZAP.ASM 

BrZOTCOM = A: <cr> Equivalent to B: Z0T.COM = A: Z0T.COM 

B: = GAMMA.BAS <cr> Same as B:GAMMA.BAS = GAMM A.BAS 

B: = A:GAMMA.BAS <cr> Same as 

B:GAMMA.BAS = A:GAMMA.BAS 

PIP also allows reference to physical and logical devices which are attached 
to the CP/M system. The device names are the same as given under the STAT 
command, along with a number of specially named devices. The logical 
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devices given in the STAT command are 

CON: (console), RDR: (reader), PUN: (punch), and LST: (Hst) 

while the physical devices are 

TTY: (console, reader, punch, or list) 
CRT: (console, or list), UCl: (console 

PTR: (reader), URl: (reader), UR2: (reader) 
FTP: (punch), UPl: (punch), UP2: (punch) 
LPT: (list), ULl: (list) 

(Note that the *'BAT:" physical device is not included, since this assignment 
is used only to indicate that the RDR: and LST: devices are to be used for 
console input/output.) 



The RDR, LST, PUN, and CON devices are all defined within the BIOS 
portion of CP/M, and thus are easily altered for any particular I/O system, 
(The current physical device mapping is defined by lOBYTE; see the 
"CP/M Interface Guide" for a discussion of this function). The destination 
device must be capable of receiving data (i.e., data cannot be sent to the 
punch), and the source devices must be capable of generating data (i.e., the 
LST: device cannot be read). 

The additional device names which can be used in PIP commands are 

NUL: Send 40 "nulls" (ASCII O's) to the device (this can be issued at the 
end of punched output). 

EOF: Send a CP/M end-of-file (ASCII ctl-Z) to the destination device 
(sent automatically at the end of all ASCII data transfers through 
PIP). 

INF: Special PIP input source which can be "patched" into the PIP 
program itself: PIP gets the input data character-by-character by 
CALLing location 103H, with data returned in location 109H 
(parity bit must be zero). 

OUT: Special PIP output destination which can be patched into the PIP 
program: PIP CALLs location 106H with data in register C for each 
character to transmit. Note that locations 109H through IFFH of 
the PIP memory image are not used and can be replaced by special 
purpose drivers using DDT (see the DDT operator's manual). 

PRN: Same as LST:, except that tabs are expanded at every eighth 

26 



character position, lines are numbered, and page ejects are inserted 
every 60 lines, with an initial eject (same as [t8np]). 

File and device names can be interspersed in the PIP commands. In each 
case, the specific device is read until end-of-file (ctl-Z for ASCII files, and a 
real end of file for non-ASCII disk files). Data from each device or file is 
concatenated from left to right until the last data source has been read. The 
destination device or file is written using the data from the source files, and 
an end-of-file character (ctl-Z) is appended to the result for ASCII files. Note 
that if the destination is a disk file, a temporary file is created ($$$ secondary 
name) which is changed to the actual file name only upon successful 
completion of the copy. Files with the extension "COM" are always assumed 
to be non-ASCIL 

The copy operation can be aborted at any time by depressing any key on the 
keyboard (a rubout suffices). PIP will respond with the message 
"ABORTED" to indicate that the operation was not completed. Note that 
if any operation is aborted, or if an error occurs during processing, PIP 
removes any pending commands which were set up while using the SUBMIT 
command. 

It should also be noted that PIP performs a special function if the destination 
is a disk file with type "HEX" (an Intel hex formatted machine code file), 
and the source is an external peripheral device, such as a paper tape reader. 
In this case, the PIP program checks to ensure that the source file contains 
a properly formed hex file, with legal hexadecimal values and checksum 
records. When an invalid input record is found, PIP reports an error message 
at the console and waits for corrective action. It is usually suflBcient to open 
the reader and rerun a section of the tape (pull the tape about 20 inches). 
When the tape is ready for the re-read, type a single carriage return at the 
console, and PIP will attempt another read. If the tape position cannot be 
properly read, simply continue the read (by typing a return following the 
error message), and enter the record manually with the ED program after 
the disk file is constructed. For convenience, PIP allows the end-of-file to be 
entered from the console if the source file is a RDR: device. In this case, the 
PIP program reads the device and monitors the keyboard. If ctl-Z is typed 
at the keyboard, then the read operation is terminated normally. 

Valid PIP commands are shown below. 

PIP LST: = X.PRN <cr> Copy X.PRN to the LST device and termin- 
ate the PIP program. 

PIP <cr> Start PIP for a sequence of commands (PIP 

prompts with"*"). 
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*CON: = X.ASM,Y.ASM,Z.ASM <cr> 

Concatenate three ASM files and copy to the 
CON device. 

*X.HEX = CON:,Y.HEX,PTR: <cr> 

Create a HEX file by reading the CON (until 
a ctl-Z is typed), followed by data from 
Y.HEX, followed by data from PTR until a 
ctl-Z is encountered. 

*<cr> Single carriage return stops PIP. 

PIP PUN: = NUL:,X.ASM,EOF:,NUL: <cr) 

Send 40 nulls to the punch device; then copy 
the X.ASM file to the punch, followed by an 
end-of-file (ctl-Z) and 40 more null 
characters. 

The user can also specify one or more PIP parameters, enclosed in left and 
right square brackets, separated by zero or more blanks. Each parameter 
affects the copy operation, and the enclosed hst of parameters must 
immediately follow the affected file or device. Generally, each parameter can 
be followed by an optional decimal integer value (the S and Q parameters are 
exceptions). The valid PIP parameters are listed below. 

B Block mode transfer: data is buffered by PIP until an ASCII x-off 

character (ctl-S) is received from the source device. This allows 
transfer of data to a disk file from a continuous reading device, such 
as a cassette reader. Upon receipt of the x-off, PIP clears the disk 
buffers and returns for more input data. The amount of data which 
can be buffered is dependent upon the memory size of the host 
system (PIP will issue an error message if the buffers overflow). 

Dn Delete characters which extend past column n in the transfer of 

data to the destination from the character source. This parameter 
is used most often to truncate long lines which are sent to a (narrow) 
printer or console device. 

E Echo all transfer operations to the console as they are being 

performed. 

F Filter form feeds from the file. All imbedded form feeds are removed. 

The P parameter can be used simultaneously to insert new form 
feeds. 

Gn Get file from user number n. (n is the range 0-15.) Allows one user 

area to receive data files from another. If the operator has issued the 
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USER 4 command at the CCP level, the PIP statement 

PIP X,Y = X.Y[G2] 
reads file X.Y from user number 2 into user area number 4. You 
cannot copy files into a different area than the one which is 
currently addressed by the USER command. 

H Hex data transfer: all data is checked for proper Intel hex file 

format. Non-essential characters between hex records are removed 
during the copy operation. The console will be prompted for 
corrective action in case errors occur. 

I Ignore ":00'* records in the transfer of Intel hex format file (the I 

parameter automatically sets the H parameter). 

L Translate upper case alphabetics to lower case. 

N Add line numbers to each line transferred to the destination, 

starting at one, and incrementing by 1. Leading zeroes are 
suppressed, and the number is followed by a colon. If N2 is specified, 
then leading zeroes are included, and a tab is inserted following the 
number. The tab is expanded if T is set. 

Object file (non-ASCII) transfer: the normal CP/M end of file is 

ignored. 

Pn Include page ejects at every n lines (with an initial page eject). If n 

= 1 or is excluded altogether, page ejects occur every 60 lines. If the 
F parameter is used, form feed suppression takes place before the 
new page ejects are inserted. 

QsTz Quit copying from the source device or file when the string s 
(terminated by ctl-Z) is encountered. 

R Read system files. Allows files with the system attribute to be 

included in PIP transfers. Otherwise, system files are not 
recognized. 

SsTz Start copying from the source device when the string s is 
encountered (terminated by ctl-Z). The S and Q parameters can be 
used to "abstract" a particular section of a file (such as a 
subroutine). The start and quit strings are always included in the 
copy operation. 

NOTE — the strings following the s and q parameters are translated 
to upper case by the CCP if form (2) of the PIP command is used. 
Form (1) of the PIP invocation, however, does not perform the 
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automatic upper case translation. 
(l)PIP<cr> 
(2) PIP "command line" < cr> 

Tn Expand tabs (ctl-I characters) to every nth column during the 

transfer of characters to the destination from the source. 

U TYanslate lower case alphabetics to upper case during the copy 

operation. 

V Verify that data has been copied correctly by rereading after the 

write operation (the destination must be a disk file). 

W Write over R/0 files without console interrogation. Under normal 

operation, PIP will not automatically overwrite a file which is set 
to a permanent R/0 status. It advises the user of the R/0 status 
and waits for overwrite approval. W allows the user to bypass this 
interrogation process. 

Z Zero the parity bit on input for each ASCII character. 

The following are valid PIP commands which specify parameters in the file 
transfer: 

PIP X.ASM = B:[v] <cr> Copy X.ASM from drive B to the current 

drive and verify that the data was properly 
copied. 

PIP LPT: = X.ASM[nt8u] <cr> 

Copy X.ASM to the LPT: device; number 
each line, expand tabs to every eighth column, 
and translate lower case alphabetics to upper 
case. 

PIP PUN: = X.HEX[i],Y.ZOT[h] <cr> 

First copy X.HEX to the PUN: device and 
ignore the trailing ":00" record in X.HEX; 
then continue the transfer of data by reading 
Y.ZOT, which contains hex records, including 
any ":00'* records which it contains. 

PIP X.LIB = Y.ASM [ sSUBRl:tz qJMP L3Tz ] <cr> 

Copy from the file Y.ASM into the file X.LIB. 
Start the copy when the string "SUBRl:" has 
been found, and quit copying after the string 
"JMP L3" is encountered. 
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PIP PRN: = X.ASM[p50] Send X.ASM to the LST: device, with line 

numbers, tabs expanded to every eighth 
column, and page ejects at every 50th line. 
Note that nt8p60 is the assumed parameter 
list for a PRN file; p50 overrides the default 
value. 

Note that the PIP program itself is initially copied to a user area (so that 
subsequent files can be copied) using the SAVE command. The sequence of 
operations shown below effectively moves PIP from one user area to the 
next. 

USER login user 

DDT PIP.COM load PIP in memory 

(note PIP size s) 

GO return to CCP 

USER 3 login user 3 

SAVEsPIP.com 

where s is the integral number of memory "pages" (256 byte segments) 
occupied by PIP The number s can be determined when PIRCOM is located 
under DDT, by referring to the value under the "NEXT" display. If for 
example, the next available address is IDOO, then PIP.COM requires IC 
hexadecimal pages (or 1 times 16 + 12 = 28 pages), and thus the value of s is 28 
in the subsequent save. Once PIP is copied in this manner, it can then be 
copied to another disk belonging to the same user number through normal 
PIP transfers. 



ED 

The ED program is the CP/M system context editor, which allows creation 
and alteration of ASCII files in the CP/M environment. Complete details of 
operation are given in Chapter 3 CP/M ED. In general, ED allows the 
operator to create and operate upon source files which are organized as a 
sequence of ASCII characters, separated by end-of-line characters (a 
carriage-return line-feed sequence). There is no practical restriction on line 
length (no single line can exceed the size of the working memory), which is 
instead defined by the number of characters typed between (cr>*s. The ED 
program has a number of commands for character string searching, 
replacement, and insertion, which are useful in the creation and correction 
of programs or text files under CP/M. Although the CP/M has a limited 
memory work space area (approximately 50(X) characters in a 16K CP/M 
system), the file size which can be edited is not limited, since data is easily 
"paged" through this work area. 

Upon initiation, ED creates the specified source file, if it does not exist, and 
opens the file for access. The programmer then "appends" data from the 
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source file into the work area, if the source file already exists (see the A 
command), for editing. The appended data can then be diisplayed, altered, 
and written from the work area back to the disk (see the W command). 
Particular points in the program can be automatically paged and located by 
context (see the N command), allowing easy access to particular portions of 
a large file. 

Given that the operator has typed 

ED X.ASM <cr> 

the ED program creates an intermediate work file with the name 



to hold the edited data during the ED run. Upon completion of ED, the 
X.ASM file (original file) is renamed to X.BAK, and the edited work file is 
renamed to X.ASM. Thus, the X.BAK file contains the original (unedited) 
file, and the X.ASM file contains the newly edited file. The operator can 
always return to the previous version of a file by removing the most recent 
version, and renaming the previous version. Suppose, for example, that the 
current X.ASM file was improperly edited; the sequence of CCP commands 
shown below would reclaim the backup file. 

DIR X.* Check to see that BAK file is available. 

ERA X.ASM Erase most recent version. 

REN X.ASM = X.BAK Rename the BAK file to ASM. 



Note that the operator can abort the edit at any point (reboot, power failure, 
ctl-C, or Q command) without destroying the original file. In this case, the 
BAK file is not created, and the original file is always intact. 

The ED program also allows the user to "ping-pong" the source and create 
backup files between two disks. The form of the ED command in this case is 

ED ufn d: 

where ufn is the name of a file to edit on the currently logged disk and d is the 
name of an alternate drive. The ED program reads and processes the 
source file, and writes the new file to drive d, using the name ufn. Upon 
completion of processing, the original file becomes the backup file. Thus, if 
the operator is addressing disk A, the following command is valid: 
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ED X.ASM B: 

which edits the file X.ASM on drive A, creating the new file X.$$$ on drive 
B. Upon completion of a successful edit, ArX.ASM is renamed to ArX.BAK, 
and B:X.$$$ is renamed to B:X.ASM. For user convenience, the currently 
logged disk becomes drive B at the end of the edit. Note that if a file by the 
name B:X.ASM exists before the editing begins, the message 

FILE EXISTS 

is printed at the console as a precaution against accidentally destroying a 
source file. In this case, the operator must first ERAse the existing file and 
then restart the edit operation. 

Similar to other transient commands, editing can take place on a drive 
different from the currently logged disk by preceding the source file name by 
a drive name. Examples of valid edit requests are shown below 

ED A:X.ASM Edit the file X.ASM on drive A, with new file and 

backup on drive A. 

ED BtX.ASM A: Edit the file X.ASM on drive B to the temporary 

file X.$$$ on drive A, On termination of editing, 
change X.ASM on drive B to X.B AK, and change 
X.$$$ on drive A to X.ASM. 



ED takes file attributes into account. If the operator attempts to edit a 
read /only file, the message 

**FILE IS READ/ONLY** 

appears at the console. The file can be loaded and examined, but cannot be 
altered in any way. Normally the operator simply ends the edit session, and 
uses STAT to change the file attribute to R/W. If the edited file has the 
system attribute set, the message 

"SYSTEM" FILE NOT ACCESSIBLE 

is displayed at the console, and the edit session is aborted. Again, the STAT 
program can be used to change the system attribute if desired. 



SUBMIT 

The SUBMIT command allows CP/M commands to be batched together for 
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automatic processing. The format of SUBMIT is: SUBMIT ufn 
parm #l...parm #n<cr>. 

The ufn given in the SUBMIT command must be the filename of a file which 
exists on the currently logged disk, with an assumed file type of "SUB!' The 
SUB file contains CP/M prototype commands, with possible parameter 
substitution. The actual parameters parm #1 ... parm #n are substituted 
into the prototype commands, and, if no errors occur, the file of substituted 
commands is processed sequentially by CP/M. 

The prototype command file is created using the ED program, with 
interspersed "$" parameters of the form 

$1 $2 $3 ... $n 

corresponding to the number of actual parameters which will be included 
when the file is submitted for execution. When the SUBMIT transient is 
executed, the actual parameters parm #1 ... parm #n are paired with the 
formal parameters $1 ...$n in the prototype commands. If the number of 
formal and actual parameters does not correspond, then the submit function 
is aborted with an error message at the console. The SUBMIT function 
creates a file of substituted commands with the name 

$$$.SUB 

on the logged disk. When the system reboots (at the termination of the 
SUBMIT), this command file is read by the CCP as a source of input, rather 
than the console. If the SUBMIT function is performed on any disk other 
than drive A, the commands are not processed until the disk is inserted into 
drive A and the system reboots. Further, the user can abort command 
processing at any time by typing a rubout when the command is read and 
echoed. In this case, the $$$.SUB file is removed, and the subsequent 
commands come from the console. Command processingis also aborted if the 
CCP detects an error in any of the commands. Programs which execute 
under CP/M can abort processing of command files when error conditions 
occur by simply erasing any existing $$$.SUB file. 

In order to introduce dollar signs into a SUBMIT file, the user may type a 
"$$" which reduces to a single **$" within the command file. Further, an 
up-arrow symbol " T "may precede an alphabetic character x, which produces 
a single ctl-x character within the file. 

The last command in a SUB file can initiate another SUB file, thus allowing 
chained batch commands. 

Suppose the file ASMBL.SUB exists on disk and contains the prototype 
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commands 

ASM $1 
DIR $1.* 
ERA *.BAK 
PIP$2:=$1.PRN 
ERA $LPRN 

and the command 

SUBMIT ASMBL X PRN <cr> 

is issued by the operator. The SUBMIT program reads the ASMBL.SUB file, 
substituting "X" for all occurrences of $1 and "PRN" for all occurrences of 
$2, resulting in a $$$.SUB file containing the commands 

ASMX 
DIR X.* 
ERA ♦.BAK 
PIPPRN: = X,PRN 
ERA X.PRN 

which are executed in sequence by the CCP. 

The SUBMIT function can access a SUB file which is on an alternate drive 
by preceding the file name by a drive name. Submitted files are only acted 
upon, however, when they appear on drive A. Thus, it is possible to create a 
submitted file on drive B which is executed at a later time when it is inserted 
in drive A. 



XSUB 

XSUB extends the power of the SUBMIT facility to include character input 
during program execution as well as entering command lines. The XSUB 
command is included as the first line of your submit file and, when executed, 
self-relocates directly below the CCR 

All subsequent submit command lines are processed by XSUB, so that 
programs which read buffered console input (BDOS function 10) receive 
their input directly from the submit file. For example, the file SAVER.SUB 
could contain the submit lines: 
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XSUB 

DDT 

I$LHEX 

R 

GO 

SAVE 1 $2.C0M 

with a subsequent SUBMIT command: 

SUBMIT SAVER XY 

which substitutes X for $1 and Y for $2 in the command stream. The XSUB 
program loads, followed by DDT which is sent the command lines 
"IX.HEX" "R" and "GO", thus returning to the CCP. The final command 
"SAVE 1 Y.COM" is processed by the OCR 

The XSUB program remains in memory, and prints the message 

(xsub active) 

on each warm start operation to indicate its presence. Subsequent submit 
command streams do not require the XSUB, unless an intervening cold 
start has occurred. Note that XSUB must be loaded after DESPOOL, if both 
are to run simultaneously. 

DUMP 

The DUMP program types the contents of the disk file (ufn) at the console 
in hexadecimal form. The file contents are listed sixteen bytes at a time, with 
the absolute byte address listed to the left of each Hne in hexadecimal. Long 
typeouts can be aborted by pushing the rubout key during printout. (The 
source listing of the DUMP program is given in the "CP/M Interface Guide" 
as an example of a program written for the CP/M environment.) 



BDOS Error Messages 



There are three error situations which the Basic Disk Operating System 
intercepts during file processing. When one of these conditions is detected, 
the BDOS prints the message: 

BDOS ERR ON x: error 

where x is the drive name, and "error" is one of the three error messages: 

BAD SECTOR 
SELECT 
READ ONLY 
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The "BAD SECTOR" message indicates that the disk controller electronics 
has detected an error condition in reading or writing the diskette. This 
condition is generally due to a malfunctioning disk controller, or an 
extremely worn diskette. If you find that your system reports this error more 
than once a month, you should check the state of your controller electronics, 
and the condition of your media. You may also encounter this condition in 
reading files generated by a controller produced by a different manufacturer. 
Even though controllers are claimed to be IBM-compatible, one often finds 
small differences in recording formats. The MDS-800 controller, for 
example, requires two bytes of one's following the data CRC byte, which is 
not required in the IBM format. As a result, diskettes generated by the Intel 
MDS can be read by almost all other IBM-compatible systems, while disk 
files generated on other manufacturers* equipment will produce the "BAD 
SECTOR'* message when read by the MDS. In any case, recovery from this 
condition is accomplished by typing a ctl-C to reboot (this is the safest! ), or 
a return, which simply ignores the bad sector in the file operation. Note, 
however, that typing a return may destroy your diskette integrity if the 
operation is a directory write, so make sure you have adequate backups in 
this case. 

The "SELECT" error occurs when there is an attempt to address a drive 
beyond the A through D range. In this case, the value of x in the error message 
gives the selected drive. The system reboots following any input from the 
console. 

The "READ ONLY" message occurs when there is an attempt to write to a 
diskette which has been designated as read-only in a STAT command, or has 
been set to read-only by the BDOS. In general, the operator should reboot 
CP/M either by using the warm start procedure (ctl-C) or by performing a 
cold start whenever the diskettes are changed. If a changed diskette is to be 
read but not written, BDOS allows the diskette to be changed without the 
warm or cold start,, but internally marks the drive as read-only. The status 
of the drive is subsequently changed to read /write if a warm or cold start 
occurs. Upon issuing this message, CP/M waits for input from the console. 
An automatic warm start takes place following any input. 



37 



38 



CP/M 2.2 INTERFACE GUIDE 



COPYRIGHT (c) 1979 
DIGITAL RESEARCH 



Copyright (c) 1979 by Digital Research. All rights re- 
served. No part of this publication may be reproduced, 
transmitted, transcribed, stored in a retrieval system, or 
translated into any language or computer language, in 
any form or by any means, electronic, mechanical, mag- 
netic, optical, chemical, manual or otherwise, without 
the prior written permission of Digital Research, Post 
Office Box 579, Pacific Grove, California 93950. 

Disclaimer 

Digital Research makes no representations or warranties 
with respect to the contents hereof and specifically 
disclaims any implied warranties of merchantability or 
fitness for any particular purpose. Further, Digital 
Research reserves the irght to revise this publication 
and to make changes from time to time in the content 
hereof without obligation of Digital Research to notify 
any person of such revision or changes. 



Table of Contents 

SECTION II Page 

1. INTRODUCTION 41 

2. OPERATING SYSTEM CALL CONVENTIONS 43 

3. A SAMPLE FILE-TO-FILE COPY PROGRAM 63 

4. A SAMPLE FILE DUMP UTILITY 66 

5. A SAMPLE RANDOM ACCESS PROGRAM 69 

6. SYSTEM FUNCTION SUMMARY 76 



39 



Introduction 

This manual describes CP/M, release 2, system organization including the 
structure of memory and system entry points. The intention is to provide the 
necessary information required to write programs which operate under 
CP/M, and which use the peripheral and disk I/O facilities of the system. 

CP/M is logically divided into four parts, called the Basic I/O System 
(BIOS), the Basic Disk Operating System (BDOS), the Console command 
processor (CCP), and the TVansient Program Area (TPA). The BIOS is a 
hardware-dependent module which defines the exact low level interface to a 
particular computer system which is necessary for peripheral device I/O. 
The BIOS and BDOS are logically combined into a single module with a 
common entry point, and referred to as the FDOS. The CCP is a distinct 
program which uses the FDOS to provide a human-oriented interface to the 
information which is cataloged on the backup storage device. The TPA is an 
area of memory (i.e., the portion which is not used by the FDOS and CCP) 
where various non-resistant operating system commands and user programs 
are executed. The lower portion of memory is reserved for system 
information and is detailed in later sections. Memory organization of the 
CP/M system is shown below: 



high 
memory 

FBASE: 



CBASE: 



TBASE: 
BOOT: 



FDOS (BDOS + BIOS) 



CCP 



TPA 



System parameters 



In standard CP/M 2.0, 

BDOS size: 
CCP size: 



EOOH bytes 
800H bytes 
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All standard CP/M versions assume BOOT = 0000H, which is the base of 
random access memory. The machine code found at location BOOT 
performs a system "warm start" which loads and initializes the programs and 
variables necessary to return control to the CCP. Thus, transient programs 
need only jump to location BOOT to return control to CP/M at the 
command level. Further, the standard versions assume 
TBASE = BOOT+0100H which is normally location OlOOH. The principal 
entry point to the FDOS is at location BOOT-I-0005H (normally 0005H) 
where a jump to FBASE is found. The address field at BOOT + 0006H 
(normally 0006H) contains the value of FBASE and can be used to determine 
the size of available memory, assuming the CCP is being overlayed by a 
transient program. 

TVansient programs are loaded into the TPA and executed as follows. The 
operator communicates with the CCP by typing command lines following 
each prompt. Each command line takes one of the forms: 

command 
command filel 
command filel file2 

where "command" is either a built-in function such as DIR or TYPE, or the 
name of a transient command or program. If the command is a built-in 
function of CP/M, it is executed immediately. Otherwise, the CCP searches 
the currently addressed disk for a file by the name 

command.COM 

If the file is found, it is assumed to be a memory image of a program which 
executes in the TPA, and thus implicitly originates at TBASE in memory. 
The CCP loads the COM file from the disk into memory starting at TBASE 
and possibly extending up to CBASE. 

If the command is followed by one or two file specifications, the CCP 
prepares one or two file control block (FCB) names in the system parameter 
area. These optional FCB's are in the form necessary to access files through 
the FDOS, and are described in the next section. 

The transient program receives control from the CCP and begins execution, 
perhaps using the I/O facilities of the FDOS. The transient program is 
"called" from the CCP, and thus can simply return to the CCP upon 
completion of its processing, or can jump to BOOT to pass control back to 
CP/M. In the first case, the transient program must not use memory above 
CBASE, while in the latter case, memory up through FBASE -1 is free. 
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The transient program may use the CP/M I/O facilities to communicate 
with the operator's console and peripheral devices, including the disk 
subsystem. The I/O system is accessed by passing a "function number'* and 
an "information address" to CP/M through the FDOS entry point at 
BOOT + 0005H. In the case of a disk read, for example, the transient program 
sends the number corresponding to a disk read, along with the address of an 
FCB to the CP/M FDOS. The FDOS, in turn, performs the operation and 
returns with either a disk read completion indication or an error number 
indicating that the disk read was unsuccessful. The function numbers and 
error indicators are given below. 

Operating System Call Conventions 

The purpose of this section is to provide detailed information for performing 
direct operating system calls from user programs, 

CP/M facilities which are available for access by transient programs fall into 
two general categories: simple device I/O, and disk file I/O. The simple 
device operations include: 

Read a Console Character 
Write a Console Character 
Read a Sequential Tape Character 
Write a Sequential Tape Character 
Write a List Device Character 
Get or Set I/O Status 
Print Console Buffer 
Read Console Buffer 
Interrogate Console Ready 



The FDOS operations which perform disk Input/Output are 

Disk System Reset 

Drive Selection 

File Creation 

File Open 

File Close 

Directory Search 

File Delete 

File Rename 

Random or Sequential Read 

Random or Sequential Write 

Interrogate Available Disks 

Interrogate Selected Disk 

Set DMA Address 

Set/ Reset File Indicators 
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As mentioned above, access to the FDOS functions is accomplished by 
passing a function number and information address through the primary 
entry point at location BOOT + 0005H. In general, the function number is 
passed in register C with the information address in the double byte pair DE. 
Single byte values are returned in register A, with double byte values 
returned in HL (a zero value is returned when the function number is out of 
range). For reasons of compatibility, register A = L and register B = H upon 
return in all cases. Note that the register passing conventions of CP/M agree 
with those of Intel's PL/M systems programming language. The list of 
CP/M function numbers is given below. 

System Reset 19 Delete File 

1 Console Input 20 Read Sequential 

2 Console Output 21 Write Sequential 

3 Reader Input 22 Make File 

4 Punch Output 23 Rename File 

5 list Output 24 Return Login Vector 

6 Direct Console I/O 25 Return Current Disk 

7 Get I/O Byte 26 Set DMA Address 

8 Set I/O Byte 27 Get Addr (Alloc) 

9 Print String 28 Write Protect Disk 

10 Read Console Buffer 29 Get R/0 Vector 

11 Get Console Status 30 Set File Attributes 

12 Return Version Number 31 Get Addr (Disk Farms) 

13 Reset Disk System 32 Set/Get User Code 

14 Select Disk 33 Read Random 

15 Open File 34 Write Random 

16 Close File 35 Compute File Size 

17 Search for First 36 Set Random Record 

18 Search for Next 

(Functions 28 and 32 should be avoided in application programs to maintain 
upward compatibility with MP/M.) 

Upon entry to a transient program, the CCP leaves the stack pointer set to 
an eight level stack area with the CCP return address pushed onto the stack, 
leaving seven levels before overflow occurs. Although this stack is usually 
not used by a transient program (i.e., most transients return to the CCP 
through a jump to location OOOOH), it is sufficiently large to make CP/M 
system calls since the FDOS switches to a local stack at system entry. The 
following assembly language program segment, for example, reads char- 
acters continuously until an asterisk is encountered, at which time control 
returns to the CCP (assuming a standard CP/M system with 
BOOT + OOOOH): 
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BDOS 


EQU 


0005H 


CONIN 


EQU 


1 


> 


ORG 


OlOOH 


NEXTC: 


MVI 


C.CONIN 




CALL 


BDOS 




CPI 


(4c» 




JNZ 


NEXTC 




RET 






END 





;STANDARD CP/M ENTRY 
;CONSOLE INPUT FUNCTION 

;BASEOFTPA 

;READ NEXT CHARACTER 

;RETURN CHARACTER IN <A> 

;END OF PROCESSING? 

;LOOP IF NOT 

;RETURN TO CCP 



CP/M implements a named file structure on each disk, providing a logical 
organization which allows any particular file to contain any number of 
records from completely empty, to the full capacity of the drive. Each drive 
is logically distinct with a disk directory and file data area. The disk file 
names are in three parts: the drive select code, the file name consisting of one 
to eight non-blank characters, and the file type consisting of zero to three 
non-blank characters. The file type names the generic category of a 
particular file, while the file name distinguishes individual files in each 
category. The file types listed below name a few generic categories which 
have been established, although they are generally arbitrary: 



ASM Assembler Source 

PRN Printer Listing 

HEX Hex Machine Code 

BAS Basic Source File 

INT Intermediate Code 

COM CCP Command File 



PLI 

REL 

TEX 

BAK 

SYM 



PL/ 1 Source File 
Relocatable Module 
TEX Formatter Source 
ED Source Backup 
SID Symbol File 
Temporary File 



Source files are treated as a sequence of ASCII characters, where each "line" 
of the source file is followed by a carriage-return line-feed sequence (ODH 
followed by OAH). Thus one 128 byte CP/M record could contain several 
lines of source text. The end of an ASCII file is denoted by a control-Z 
character (lAH) or a real end of file, returned by the CP/M read operation. 
Control-Z characters embedded within machine code files (e.g., COM files) 
are ignored, however, and the end of file condition returned by CP/M is used 
to terminate read operations. 

Files in CP/M can be thought of as a sequence of up to 65536 records of 128 
bytes each, numbered from through 65535, thus allowing a maximum of 8 
megabytes per file. Note, however, that although the records may be 
considered logically contiguous, they may not be physically contiguous in 
the disk data area. Internally, all files are broken into 16K byte segments 
called logical extents, so that counters are easily maintained as 8-bit values. 
Although the decomposition into extents is discussed in the paragraphs 
which follow, they are of no particular consequence to the programmer since 
each extent is automatically accessed in both sequential and random access 
modes. 
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In the file operations starting with function number 15, DE usually 
addresses a file control block (FCB). TVansient programs often use the 
default file control block area reserved by CP/M at location BOOT + 005CH 
(normally 005CH) for simple file operations. The basic unit of file 
information is a 128 byte record used for all file operations, thus a default 
location for disk I/O is provided by CP/M at location BOOT + 0080H 
(normally 0080H) which is the initial default DMA address (see function 26). 
All directory operations take place in a reserved area which does not affect 
write buffers as was the case in release 1, with the exception of Search First 
and Search Next, where compatibility is required. 

The File Control Block (FCB) data area consists of a sequence of 33 bytes for 
Sequential access and a series of 36 bytes in the case that the file is accessed 
randomly. The default file control block normally located at 005CH can be 
used for random access files, since the three bytes starting at BOOT + 007DH 
are available for this purpose. The FCB format is shown with the following 
fields: 



1- 


fl 


f2 


/ / 


fB 


tl 


t2 


t3 


ex 


si 


s2 


rc 


do|/ / 


dn 


cr 


rO 


rl 


'H 


00 


01 


02 




08 


09 


10 


11 


12 


13 


14 


15 


16 ... 


31 


32 


33 


34 


35 



where 



dr 



drive code (0 - 16) 

= >use default drive for file 

1 = >auto disk select drive A, 

2 = >auto disk select drive B, 



16 = > auto disk select drive P. 

fl. . .f8 contain the file name in ASCII upper case, with high bit = 

tl,t2,t3 contain the file type in ASCII upper case, with high bit = 

tl', t2', and t3* denote the bit of these positions, 
tr = l = >Read/Onlyfile, 
t2' = 1 = > SYS file, no DIR list 



ex 



contains the current extent number, normally set to 00 by the 
user, but in range 0-31 during file I/O 



si 
s2 



reserved for internal system use 

reserved for internal system use, set to zero on call to OPEN, 
MAKE, SEARCH 



rc 



record count for extent "ex," takes on values from - 128 
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do. . .dn fiUed-in by CP/M, reserved for system use 

cr current record to read or write in a sequential file operation, 

normally set to zero by user 

rO,rl,r2 optional random record number in the range 0-65535, with 

overflow to r2, rO,rl constitute a 16-bit value with low byte rO, 
and high byte rl 



Each file being accessed through CP/M must have a corresponding FCB 
which provides the name and allocation information for all subsequent file 
operations. When accessing files, it is the programmer's responsibility to fill 
the lower sixteen bytes of the FCB and initiaUze the **cr" field. Normally, 
bytes 1 through 11 are set to the ASCII character values for the file name and 
file type, while all other fields are zero. 

FCB's are stored in a directory area of the disk, and are brought into central 
memory before proceeding with file operations (see the OPEN and MAKE 
functions). The memory copy of the FCB is updated as file operations take 
place and later recorded permanently on disk at the termination of the file 
operation (see the CLOSE command). 

The CCP constructs the first sixteen bytes of two optional FCB's for a 
transient by scanning the remainder of the line following the transient name, 
denoted by "filel" and **file2" in the prototype command line described 
above, with unspecified fields set to ASCII blanks. The first FCB is 
constructed at location BOOT + 005CH, and can be used as-is for subsequent 
file operations. The second FCB occupies the dO . . . dn portion of the first 
FCB, and must be moved to another area of memory before use. If, for 
example, the operator types 

PROGNAME BiX.ZOT Y.ZAP 

the file PROGNAME. COM is loaded into the TPA, and the default FCB at 
BOOTH-005CH is initialized to drive code 2, file name "X" and file type 
"ZOT" The second drive code takes the default value 0, which is placed at 
BOOT + 006CH, with the file name " Y" placed into location BOOT + 006DH 
and file type "ZAP" located 8 bytes later at BOOT-h0075H. All remaining 
fields through **cr" are set to zero. Note again that it is the programmer's 
responsibility to move this second file name and type to another area, usually 
a separate file control block, before opening the file which begins at 
BOOT + 005CH, due to the fact that the open operation will overwrite the 
second \iame and type. 

If no file names are specified in the original command, then the fields 
beginning at BOOT-I-005DH and BOOT + 006DH contain blanks. In all 
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cases, the CCP translates lower case alphabetics to upper case to be 
consistent with the CP/M file naming conventions. 

As an added convenience, the default buffer area at location BOOT + 0080H 
is initialized to the command line tail typed by the operator following the 
program name. The first position contains the number of characters, with 
the characters themselves following the character count. Given the above 
command line, the area beginning at BOOT + 0080H is initialized as follows: 

BOOT + 0080H: 

+ 00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +10 +11 +12 +13 +14 
14 * B" *':" "X" "/' "Z" "0" "T Y*' "." **Z" "A" "P" 

where the characters are translated to upper case ASCII with unintialized 
memory following the last valid character. Again, it is the responsibility of 
the programmer to extract the information from this buffer before any file 
operations are performed, unless the default DMA address is explicitly 
changed. 

The individual functions are described in detail in the pages which follow. 

FUNCTION 0: System Reset 

Entry Parameters : 
Register C: OOH 

The system reset function returns control to the CP/M operating system at 
the CCP level. The CCP re-initializes the disk subsystem by selecting and 
logging-in disk drive A. This function has exactly the same effect as a jump 
to location BOOT. 

FUNCTION 1: CONSOLE INPUT 

Entry Parameters : 
Register C: OIH 

Returned Value : 

Register A: ASCII Character 

The console input function reads the next console character to register A. 
Graphic characters, along with carriage return, line feed, and backspace 
(ctl-H) are echoed to the console. Tab characters (ctl-I) are expanded in 
columns of eight characters. A check is made for start/stop scroll (ctl-S) and 
start/stop printer echo (ctl-P). The FDOS does not return to the calling 
program until a character has been typed, thus suspending execution of a 
character if not ready. 
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FUNCTION 2: CONSOLE OUTPUT 

Entry Parameters : 

Register C: 02H 

Itegister E: ASCII Character 

The ASCII character from register E is sent to the console device. Similar to 
function 1, tabs are expanded and checks are made for start/stop scroll and 
printer echo. 

FUNCTION 3: READER INPUT 

Entry Parameters : 

Register C: 03H 

Returned Value : 

Register A: ASCII Character 

The Reader Input function reads the next character from the logical reader 
into register A. Control does not return until the character has been read. 

FUNCTION 4: PUNCH OUTPUT 

Entry Parameters : 

Register C: 04H 

Register E: ASCII Character 

The Punch Output function sends the character from register E to the 
logical punch device. 

FUNCTION 5: LIST OUTPUT 

Entry Parameters : 

Register C: 05H 

Register E: ASCII Character 

The List Output function sends the ASCII character in register E to the 
logical listing device. 
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FUNCTIONS: DIRECT CONSOLE I/O 

Entry Parameters : 

Register C: 06H 
Register E: OFFH (input) or 
char (output) 

Returned Value : 

Register A: char or status 
(no value) 

Direct console I/O is supported under CP/M for those specialized 
applications where unadorned console input and output is required. Use of 
this function should, in general, be avoided since it bypasses all of CP/M's 
normal control character functions (e.g., control-S and control-P). 
Programs which perform direct I/O through the BIOS under previous 
releases of CP/M, however, should be changed to use direct I/O under BDOS 
so that they can be fully supported under future releases of MP/M and 
CP/M, 

Upon entry to function 6, register E either contains hexadecimal FF, 
denoting a console input request, or register E contains an ASCII character. 
If the input value is FF, then function 6 returns A = 00 if no character is ready, 
otherwise A contains the next console input character 

If the input value in E is not FF, then function 6 assumes that E contains a 
valid ASCII character which is sent to the console. 

FUNCTION?: GET I/O BYTE 

Entry Parameters: 

Register C: 07H 

Returned Value: 
Register A: I/O Byte Value 

The Get I/O Byte function returns the current value of lOBYTE in register 

A. 

FUNCTION 8: SET I/O BYTE 

Entry Parameters : 

Register C: 08H 

Register E: I/O Byte Value 
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The Set I/O Byte function changes the system lOB YTE value to that given 
in register E. 

FUNCTION 9: PRINT STRING 

Entry Parameters : 

Register C: 09H 
Registers DE: String Address 

The Print String function sends the character string stored in memory at the 
location given by DE to the console device, until a "$" is encountered in the 
string. Tabs are expanded as in function 2, and checks are made for start/stop 
scroll and printer echo. 

FUNCTION 10: READ CONSOLE BUFFER 

Entry Parameters: 

Register C: OAH 
Registers DE: Buffer Address 

Returned Value : 

Console Characters in Buffer 



The Read Buffer function reads a line of edited console input into a buffer 
addressed by registers DE. Console input is terminated when either the input 
buffer overflows. The Read Buffer takes the form: 

DE: +0+1+2 +3 +4 +5 +6 +7 +8 ... +n 



mx nc cl c2 c3 c4 c5 c6 c7 



where "mx" is the maximum number of characters which the buffer will hold 
(1 to 255), "nc" is the number of characters read (set by FDOS upon return), 
followed by the characters read from the console. If nc < mx, then 
uninitialized positions follow the last character, denoted by "??" in the above 
figure. A number of control functions are recognized during line editing: 

rub /del removes the echoes the last character 

ctl-C reboots when at the beginning of line 

ctl-E causes physical end of line 

ctl-H backspaces one character position 

ctl-J (line feed) terminates input line 

ctl-M (return) terminates input line 

ctl-R retypes the current line after new line 

ctl-X backspaces to beginning of current line 

Note also that certain functions which return the carriage to the leftmost 
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position (e.g., ctl-X) do so only to the column position where the prompt 
ended (in earlier releases, the carriage returned to the extreme left margin). 
This convention makes operator data input and line correction more legible. 

FUNCTION 11: GET CONSOLE STATUS 

Entry Parameters : 

Register C: OBH 

Return Value : 

Register A: Console Status 

The Console Status function checks to see if a character has been typed at 
the console. If a character is ready, the value OFFH is returned in register A. 
Otherwise a OOH value is returned. 

FUNCTION 12: RETURN VERSION NUMBER 

Entry Parameters : 

Register C: OCH 

Returned Value 

Registers HL: Version Number 

Function 12 provides information which allows version independent 
programming. A two-byte value is returned, with H = 00 designating the 
CP/M release (H = 01 for MP/M), and L = 00 for all releases previous to 2.0. 
CP/M 2.0 returns a hexadecimal 20 in register L, with subsequent version 2 
releases in the hexadecimal range 21, 22, through 2F. Using function 12, for 
example, you can write application programs which provide both sequential 
and random access functions, with random access disabled when operating 
under early releases of CP/M. 

FUNCTION 13: RESET DISK SYSTEM 

Entry Parameters : 

Register C: ODH 

The Reset Disk Function is used to programmatically restore the file system 
to a reset state where all disks are set to read/write (see functions 28 and 29), 
only disk drive A is selected, and the default DMA address is reset to 
BOOT+0080H. This function can be used, for example, by an application 
program which requires a disk change without a system reboot. 
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FUNCTION 14: SELECT DISK 

Entry Parameters : 

Register C: OEH 
Register E: Selected Disk 

The Select Disk function designates the disk drive named in register E as the 
default disk for subsequent file operations, with E = for drive A, 1 for drive 
B, and so-forth through 15 corresponding to drive P in a full sixteen drive 
system. The drive is placed in an "on-hne" status which, in particular, 
activates its directory until the next cold start, warm start, or disk system 
reset operation. If the disk media is changed while it is on-line, the drive 
automatically goes to a read/only status in a standard CP/M environment 
(see function 28). FCB's which specify drive code zero (dr = OOH) automat- 
ically reference the currently selected default drive. Drive code values 
between 1 and 16, however, ignore the selected default drive and directly 
reference drives A through P. 

FUNCTION 15: OPEN FILE 

Entry Parameters : 

Register C: OFH 
Registers DE: FOB Address 

Returned Value 

Register A: Directory Code 

The Open File operation is used to activate a file which currently exists in the 
disk directory for the currently active user number. The FDOS scans the 
referenced disk directory for a match in positions 1 through 14 of the FCB 
referenced by DE (byte si is automatically zeroed), where an ASCII question 
mark (3FH) matches any directory character in any of these positions. 
Normally, no question marks are included and, further, bytes "ex" and **s2" 
of the F(I!B are zero. 

If a directory element is matched, the relevant directory information is 
copied into bytes dO through dn of the FCB, thus allowing access to the files 
through subsequent read and write operations. Note that an existing file 
must not be accessed until a successful open operation is completed. Upon 
return, the open function returns a "directory code" jrith the value through 
3 if the open was successful, or OFFH (255 decimal) if the file cannot be found. 
If question marks occur in the FCB then the first matching FCB is activated. 
Note that the current record ("cr") must be zeroed by the program if the file 
is to be accessed sequentially from the first record. 
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FUNCTION 16 : CLOSE FILE 

Entry Parameters : 
Register C: lOH 
Registers DE: FOB Address 

Returned Value 

Register A: Directory Code 

The Close File function performs the inverse of the open file function. Given 
that the FCB addressed by DE has been previously activated through an 
open or make function (see functions 15 and 22), the close function 
permanently records the new FCB in the referenced disk directory. The FCB 
matching process for the close is identical to the open function. The directory 
code returned for a successful close operation is 0, 1, 2, or 3, while a OFFH (255 
decimal) is returned if the file name cannot be found in the directory. A file 
need not be closed if only read operations have taken place. If write 
operations have occurred, however, the close operation is necessary to 
permanently record the new directory information. 

FUNCTION 17: SEARCH FOR FIRST 

Entry Parameters : 
Register C: llH 
Registers DE: FCB Address 

Returned Value 

Register A: Directory Code 

Search First scans the directory for a match with the file given by the FCB 
addressed by DE. The value 255 (hexadecimal FF) is returned if the file is not 
found, otherwise 0, 1, 2, or 3 is returned indicating the file is present. In the 
case that the file is found, the current DMA address is filled with the record 
containing the directory entry, and the relative starting position is A * 32 (i.e., 
rotate the A register left 5 bits, or ADD A five times). Although not normally 
required for application programs, the directory information can be 
extracted from the buffer at this position. 

An ASCII question mark (63 decimal, 3F hexadecimal) in any position from 
"fl" through "ex" matches the corresponding field of any directory entry on 
the default or auto-selected disk drive. If the "dr" field contains an ASCII 
question mark, then the auto disk selected function is disabled, the default 
disk is searched, with the search function returning any matched entry, 
allocated or free, belonging to any user number. This latter function is not 
normally used by application programs, but does allow complete flexibility 
to scan all current directory values. If the "dr" field is not a question mark, 
the "s2" byte is automatically zeroed. 
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FUNCTION 18: SEARCH FOR NEXT 

Entry Parameters : 
Register C: 12H 

Returned Value 

Register A: Directory Code 

The Search Next function is similar to the Search First function, except that 
the directory scan continues from the last matched entry. Similar to 
function 17, function 18 returns the decimal value 255 in A when no more 
directory items match, 

FUNCTION 19: DELETE FILE 

Entry Parameters : 
Register C: 13H 
Registers DE: FCB Address 

Returned Value : 

Register A: Directory Code 

The Delete File function removes files which match the FCB addresses by 
DE. The filename and type may contain ambiguous references (i.e., question 
marks in various positions), but the drive select code cannot be ambiguous, 
as in the Search and Search Next functions. 

Function 19 returns a decimal 255 if the referenced file or files cannot be 
found, otherwise a value in the range to 3 is returned. 

FUNCTION 20: READ SEQUENTIAL 

Entry Parameters : 
Register C: 14H 
Registers DE: FCB Address 

Returned Value : 

Register A: Directory Code 

Given that the FCB addressed by DE has been activated through an open or 
make function (numbers 15 and 22), the Read Sequential function reads the 
next 128 byte record from the file into memory at the current DMA address. 
The record is read from position "cr" of the extent, and the "cr" field is 
automatically incremented to the next record position. If the "cr" field 
overflows then the next logical extent is automatically opened and the "cr" 
field is reset to zero in preparation for the next read operation. The value OOH 
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is returned in the A register if the read operation was successful, while a 
non-zero value is returned if no data exists at the next record position (e.g., 
end of file occurs). 

FUNCTION 21: WRITE SEQUENTIAL 

Entry Parameters : 
. Register C: 15H 
Registers DE: FCB Address 

Returned Value 

Register A: Directory Code 

Given that the FCB addressed by DE has been activated through an open or 
make function (numbers 15 and 22), the Write Sequential function writes the 
128 byte data record at the current DMA address to the file named by the 
FCB. The record is placed at position "cr" of the file, and the **cr" field is 
automatically incremented to the next record position. If the "cr** field 
overflows then the next logical extent is automatically opened and the "cr" 
field is reset to zero in preparation for the next write operation. Write 
operations can take place into an existing file, in which case newly written 
records overlay those which already exist in the file. Register A = 00H upon 
return from a successful write operation, while a non-zero value indicates an 
unsuccessful write due to a full disk. 

FUNCTION 22: MAKE FILE 

Entry Parameters : 
Register C: 16H 
Registers DE: FCB Address 

Returned Value 

Register A: Directory Code 

The Make File operation is similar to the open file operation except that the 
FCB must name a file which does not exist in the currently referenced disk 
directory (i.e., the one named explicitly by a non-zero "dr" code, or the 
default disk if **dr*' is zero). The FDOS creates the file and initializes both the 
directory and main memory value to an empty file. The programmer must 
ensure that no duplicate file names occur, and a preceding delete operation 
is sufficient if there is any possibility of duplication. Upon return, register 
A =0, 1, 2, or 3 if the operation was successful and OFFH (255 decimal) if no 
more directory space is available. The make function has the side-effect of 
activating the FCB and thus a subsequent open is not necessary. 
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FUNCTION 23: RENAME FILE 

Entry Parameters : 
Register C: 17H 
Registers DE: FCB Address 

Returned Value 

Register A: Directory Code 

The Rename function uses the FCB addressed by DE to change all 
occurrences of the file named in the first 16 bytes to the file named in the 
second 16 bytes. The drive code **dr" at position is used to select the drive, 
while the drive code for the new file name at position 16 of the FCB is assumed 
to be zero. Upon return, register A is set to a value between and 3 if the 
rename was successful, and OFFH (255 decimal) if the first file name could 
not be found in the directory scan. 

FUNCTION 24: RETURN LOGIN VECTOR 

Entry Parameters : 
Register C: 18H 

Returned Value : 

Registers HL: Login Vector 

The login vector value returned by CP/M is a 16-bit value in HL, where the 
least significant bit of L corresponds to the first drive A, and the high order 
bit of H corresponds to the sixteenth drive, labelled P. A "0" bit indicates that 
the drive is not on-line, while a "1" bit marks a drive that is actively on-Hne 
due to an explicit disk drive selection, or an implicit drive select caused by a 
file operation which specified a non-zero "dr" field. Note that compatibility 
is maintained with earlier releases, since registers A and L contain the same 
values upon return, 

FUNCTION 25: RETURN CURRENT DISK 

Entry Parameters : 

Register C: 19H 

Returned Value 

Register A: Current Disk 

Function 25 returns the currently selected default disk number in register A. 
The disk numbers range from through 15 corresponding to drives A through 
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FUNCTION 26: SET DMA ADDRESS 

Entry Parameters : 

Regular C: lAH 
Registers DE: DMA Address 

"DMA" is an acronym for Direct Memory Address, which is often used in 
connection with disk controllers which directly access the memory of the 
mainframe computer to transfer data to and from the disk subsystem. 
Although many computer systems use non-DMA access (i.e., the data is 
transferred through programmed I/O operations), the DMA address has, in 
CP/M, come to mean the address at which the 128 byte data record resides 
before a disk write and after a disk read. Upon cold start, warm start, or disk 
system reset, the DMA address is automatically set to BOOT + 0080H. The 
Set DMA function, however, can be used to change this default value to 
address another area of memory where the data records reside. Thus, the 
DMA address becomes the value specified by DE until it is changed by a 
subsequent Set DMA function, cold start, warm start, or disk system reset. 

FUNCTION 27: GET ADDR (ALLOC) 

Entry Parameters : 

Register C: IBH 

Returned Value 

Registers HL: ALLOC Address 

An ''allocation vector" is maintained in main memory for each on-line disk 
drive. Various system programs use the information provided by the 
allocation vector to determine the amount of remaining storage (see the 
STAT program). Function 27 returns the base address of the allocation 
vector for the currently selected disk drive. The allocation information may, 
however, be invalid if the selected disk has been marked read/only. Although 
this function is not normally used by application programs, additional 
details of the allocation vector are found in the **CP/M Alteration Guide!' 

FUNCTION 28: WRITE PROTECT DISK 

Entry Parameters : 

Register C: ICH 

The disk write protect function provides temporary write protection for the 
currently selected disk. Any attempt to write to the disk, before the next cold 
or warm start operation produces the message 

Bdos Err on d: R/0 
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FUNCTION 29: GET READ/ONLY VECTOR 

Entry Parameters : 

Register C: IDH 

Returned Value 

Registers HL: R/0 Vector Value 

Function 29 returns a bit vector in register pair HL which indicates drives 
which have the temporary read/only bit set. Similar to function 24, the least 
significant bit corresponds to drive A, while the most significant bit 
corresponds to drive P. The R/0 bit is set either by the explicit call to 
function 28, or by the automatic software mechanisms within CP/M which 
detect changed disks. 

FUNCTION 30: SET FILE ATTRIBUTES 

Entry Parameters : 

Register C: lEH 
Registers DE: FOB Address 

Returned Value : 

Register A: Directory Code 

The Set File Attributes function allows programmatic manipulation of 
permanent indicators attached to files. In particular, the R/O and System 
attributes (tl' and t2*) can be set or reset. The DE pair addresses an 
unambiguous file name with the appropriate attributes set or reset. Function 
30 searches for a match, and changes the matched directory entry to contain 
the selected indicators. Indicators fl' through f4' are not presently used, but 
may be useful for applications programs, since they are not involved in the 
matching process during file open and close operations. Indicators f5' 
through (8' and t3* are reserved for future system expansion. 

FUNCTION 31: GET ADDR (DISK FARMS) 

Entry Parameters : 

Register C: IFH 

Returned Value 

Registers HL: DPB Address 

The address of the BIOS resident disk parameter block is returned in HL as 
a result of this function call. This address can be used for either of two 
purposes. First, the disk parameter values can be extracted for display and 
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space computation purposes, or transient programs can dynamically change 
the values of current disk parameters when the disk environment changes, if 
required. Normally, application programs will not require this facility. 

FUNCTION 32: SET/GET USER CODE 

Entry Parameters : 

Register C: 20H 
Register E: OFFH (get or 
User Code (set) 

Returned Value : 

Register A: Current Code or 
(no value) 

An application program can change or interrogate the currently active user 
number by caUing function 32, If register E = OFFH, then the value of the 
current user number is returned in register A, where the value is in the range 
to 31. If register E is not OFFH, then the current user number is changed to 
the value of E (modulo 32). 

FUNCTION 33: READ RANDOM 

Entry Parameters : 
Register C: 21H 
Registers DE: FCB Address 

Returned Value 

Register A: Return Code 

The Read Random function is similar to the sequential file read operation of 
previous releases, except that the read operation takes place at a particular 
record number, selected by the 24-bit value constructed from the three byte 
field following the FCB (byte positions rO at 33, rl at 34, and r2 at 35). Note 
that the sequence of 24 bits is stored with least significant byte first (rO), 
middle byte next (rl), and high byte last (r2). CP/M does not reference byte 
r2, except in computing the size of a file (function 35). Byte r2 must be zero, 
however, since a non-zero value indicates overflow past the end of file. 

Thus, the rO,rl byte pair is treated as a double-byte, or "word" value, which 
contains the record to read. This value ranges from to 65535, providing 
access to any particular record of the 8 megabyte file. In order to process a 
file using random access, the base extent (extent 0) must first be opened. 
Although the base extent may or may not contain any allocated data, this 
ensures that the file is properly recorded in the directory, and is visible in DIR 
requests. The selected record number is then stored into the random record 
field (rO,rl), and the BDOS is called to read the record. Upon return from the 
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call, register A either contains an error code, as listed below, or the value 00 
indicating the operation was successful. In the latter case, the current DMA 
address contains the randomly accessed record. Note that contrary to the 
sequential read operation, the record number is not advanced. Thus, 
subsequent random read operations continue to read the same record. 

Upon each random read operation, the logical extent and current record 
values are automatically set. Thus, the file can be sequentially read or 
written, starting from the current randomly accessed position. Note, 
however, that in this case, the last randomly read record will be re-read as you 
switch from random mode to sequential read, and the last record will be 
re-written as you switch to a sequential write operation. You can, of course, 
simply advance the random record position following each random read or 
write to obtain the effect of a sequential I/O operation. 

Error codes returned in register A following a random read are listed below. 

01 reading unwritten data 

02 (not returning in random mode) 

03 cannot close current extent 

04 seek to unwritten extent 

05 (not returned in read mode) 

06 seek past physical end of disk 

Error code 01 and 04 occur when a random read operation accesses a data 
block which has not been previously written, or an extent which has not been 
created, which are equivalent conditions. Error 3 does not normally occur 
under proper system operation, but can be cleared by simply re-reading, or 
re-opening extent zero as long as the disk is not physically write protected. 
Error code 06 occurs whenever byte r2 is non-zero under the current 2.0 
release. Normally, non-zero return codes can be treated as missing data, with 
zero return codes indicating operation complete. 

FUNCTION 34: WRITE RANDOM 

Entry Parameters : 
Register C: 22H 
Registers DE: FCB Address 

Returned Value 

Register A: Return Code 

The Write Random operation is initiated similar to the Read Random call, 
except that data is written to the disk from the current DMA address. 
Further, if the disk extent or data block which is the target of the write has 
not yet been allocated, the allocation is performed before the write operation 
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continues. As in the Read Random operation, the random record number is 
not changed as a result of the write. The logical extent number and current 
record positions of the file control block are set to correspond to the random 
record which is being written. Again, sequential read or write operations can 
commence following a random write, with the notation that the currently 
addressed record is either read or rewritten again as the sequential operation 
begins. You can also simply advance the random record position following 
each write to get the effect of a sequential write operation. Note that in 
particular, reading or writing the last record of an extent in random mode 
does not cause an automatic extent switch as it does in sequential mode. 

The error codes returned by arandom write are identical to the random read 
operation with the addition of error code 05, which indicates that a new 
extent cannot be created due to directory overflow. 

FUNCTION 36: COMPUTE FILE SIZE 

Entry Parameters : 
Register C: 23H 
Registers DE: FOB Address 

Returned Value : 

Random Record Field Set 

When computing the size of a file, the DE register pair addresses an FCB in 
random mode format (bytes rO, rl, and r2 are present). The FCB contains an 
unambiguous file name which is used in the directory scan. Upon return, the 
random record bytes contain the "virtual** file size which is, in effect, the 
record address of the record following the end of the file. If, following a call 
to function 35, the high record byte r2 is 01, then the file contains the 
maximum record count 65536. Otherwise, bytes rO and rl constitute a 16-bit 
value (rO is the least significant byte, as before) which is the file size. 

Data can be appended to the end of an existing file by simply calling function 
35 to set the random record position to the end of file, then performing a 
sequence of random writes starting at the preset record address 

The virtual size of a file corresponds to the physical size when the file is 
written sequentially. If, instead, the file was created in random mode and 
"holes** exist in the allocation, then the file may in fact contain fewer records 
than the size indicates. If, for example, only the last record of an eight 
megabyte file is written in random mode (i.e., record number 65535), then the 
virtual size is 65536 records, although only one block of data is actually 
allocated. 
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FUNCTION 36: SET RANDOM RECORD 

Entry Parameters : 
Register C: 24H 
Registers DE: FOB Address 

Returned Value 

Random Record Field Set 

The Set Random Record function causes the BDOS to automatically 
produce the random record position from a file which has been read or 
written sequentially to a particular point. The function can be useful in two 
ways. 

First, it is often necessary to initially read and scan a sequential fi le to extract 
the position of various "key" fields. As each key is encountered, function 36 
is called to compute the random record position for the data corresponding 
to this key. If the data unit size is 128 bytes, the resulting record position is 
placed into a table with the key for later retrieval. After scaning the entire 
file and tabularizing the keys and their record numbers, you can move 
instantly to a particular keyed record by performing a random read using the 
corresponding random record number which was saved earlier. The scheme 
is easily generated when variable record lengths are involved since the 
program need only store the buffer-relative byte position along with the key 
and record number in order to find the exact starting position of the keyed 
data at a later time. 

A second use of function 36 occurs when switching from a sequential read or 
write over to random read or write. A file is sequentially accessed to a 
particular point in the file, function 36 is called which sets the record number, 
and subsequent random read and write operations continue from the 
selected point in the file. 



Sample File-to-File Copy Program 

The program shown below provides a relatively simple example of file 
operations. The program source file is created as COPY.ASM using the 
CP/M ED program and then assembled using ASM or MAC, resulting in a 
"HEX" file. The LOAD program is then used to produce a C0PY.COM file 
which executes directly under the CCP The program begins by setting the 
stack pointer to a local area, and then proceeds to move the second name 
from the default area at 006CH to a 33-by te file control block called DFCB. 
The DFCB is then prepared for file operations by clearing the current record 
field. At this point, the source and destination FCB's are ready for processing 
since the SFCB at 005CH is properly set-up by the CCP upon entry to the 
COPY program. That is, the first name is placed into the default FCB, with 
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the proper fields zeroed, including the current record field at 007CH. The 
program continues by opening the source file, deleting any existing 
destination file, and then creating the destination file. If all this is successful, 
the program loops at the label COPY until each record has been read from 
the source file and placed into the destination file. Upon completion of the 
data transfer, the destination file is closed and the program returns to the 
CCP command level by jumping to BOOT. 



sample file-to-file copy program 

at the ccp level, the command 

copy a:x,y b:u,v 

copies the file named x.y from drive 
a to a file named u.v on drive b. 



0000 » 


boot 


equ 


0000h 


' system reboot 


0005 ^ 


bdos 


equ 


0005h 


bdos entry point 


005c = 


fcbl 


equ 


005ch ; 


first file name 


005c = 


sfcb 


equ 


fcbl 


source fcb 


006c = 


fcb2 


equ 


006ch 


second file name 


0080 = 


dbuff 


equ 


00d0h 


default buffer 


0100 = 


tpa 


equ 


0100h 


beginning of tpa 


0009 = 


pr intf 


equ 


9 


print buffer fund 


000f = 


openf 


equ 


15 


• open file func# 


0010 = 


closef 


equ 


16 


• close file func# 


0013 = 


deletef 


equ 


19 


' delete file func# 


0014 = 


readf 


equ 


20 


r sequential read 


0015 = 


writef 


equ 


21 


► sequential write 


0016 « 


makef 


equ 


22 


• make file func# 


0100 


? 


org 


tpa 


' beginning of tpa 


0100 311b02 




Ixi 


sp, stack 


r local stack 




; 


move s€ 


cond f ile 


name to dfcb 


0103 0el0 




mvi 


C.16 


; half an fcb 


0105 116C00 




Ixi 


d,fcb2 ! 


source of move 


0106 21da01 




Ixi 


h,dfcb 


• destination fcb 


010b la 


m£cb: 


Idax 


d 


source fcb 


010c 13 




inx 


d 


ready next 


010d 77 




mov 


m,a 


dest fcb 


010e 23 




inx 


h 


ready next 


010f 0d 




dcr 


c , 


count 16. . .0 


0110 c20b01 




jnz 


mfcb 


• loop 16 times 




; 


name ha 


s been mo^ 


/ed, zero cr 


0113 af 




xra 


a 


; a = 00h 


0114 32£a01 




sta 


dfcbcr 


; current rec = 




; 


source 


and desti 


nation fcb*s ready 


0117 115C00 


t 


Ixi 


d,sfcb 


; source file 


011a cd6901 




call 


open 


; error if 255 


011d 118701 




Ixi 


d,nofile 


; ready message 


0120 3c 




inr 


a 


; 25 5 becomes 


0121 CC6101 




cz 


finis 


; done if no file 




i 


source 


file open 


, prep destination 


0124 llda01 




Ixi 


d,dfcb 


; destination 


0127 cd7301 




call 


delete 


; remove if present 


012a llda01 


' 


Ixi 


d,dfcb 


; destination 


012d cd8201 




call 


rake 


; create the t ile 


0130 119601 




Ixi 


d.nodir 


; ready messaqe 
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0133 3c 

0134 CC6101 



inr 
cz 



a 

f inis 



2S5 becoires 

done if no dir space 



0137 


115C00 


copy: 


Ixi 


d,sfcb 


013a 


cd7801 




call 


read 


013d 


b7 




ora 


a 


013e 


C25101 




jnz 


eof lie 






; 


not end 


of file, 


0141 


llda01 




Ixi 


d,dfcb 


0144 


cd7d01 




call 


wr i te 


0147 


lla901 




Ixi 


d, space 


014a 


b7 




oca 


a 


014b 


C46101 




en- 


finis 


014e 


C33701 




jmp 


copy 






eof lie: 


; end o 


f file, c 


0151 


llda01 




Ixi 


d,dfcb 


0154 


cd6e01 




call 


close 


0157 


21bb01 




Ixi 


h,wrprot 


015a 


3c 




inc 


a 


015b 


CC6101 




cz 


finis 



015e llcc01 



0161 0e09 

0163 cd0500 
0166 C30000 



f inis: 



source file open, dest file open 
copy until end of file on source 



source 

read next record 
end of file? 
skio wr ite 1 f so 



destination 
write record 
ready message 
00 if wr ite ok 
end if so 
loop until eof 



destination 
255 if error 
ready message 
255 becomes 00 
shouldn't happen 



copy operation complete, end 
Ixi d, normal; ready message 

; write message given by de, reboot 
mvi cprintf 
call bdos ; write message 
jmp boot ; reboot system 

system interface subroutines 
(all return directly from bdos) 



0169 
016b 


0e0f 

C3fl500 


open: 


mvi 
jmp 


copenf 
bdos 


016e 
0170 


0el0 
C30500 


close: 


mvi 
jmp 


c,closef 
bdos 


0173 
0175 


0el3 

C30500 


delete: 


mvi 
jmp 


Cdeletef 

bdos 


0178 
17a 


0el4 
C3G500 


read : 


mvi 

jmp 


c , r e ad f 
bdos 


17d 
17f 


UelD 
C3O500 


wr Ite: 


mvi 
jmp 


c, wr i tef 
Ddos 


G182 
01d4 


Uelb 
C305O0 


make ; 


mvi 

jmp 


c,makef 
bdos 



lo7 6e6t20fnof ile: 
0196 6e6f209nodir: 
0la9 6t7574tspace: 
tilob 7772695wrprot: 
Jlcc 6 i6f 700norrral : 



console ires sages 

db 'no source fileS* 

db * no directory spaceS' 

db *out of data spaceS* 

db *write protected?$* 

db 'copy completes' 



laa 
dita 

Olfb 

0210 



dfcb: 
df cbcr 



stack: 



data areas 
ds 33 
equ dfcb+32 



as 
end 



32 



destination fcb 
current record 

; 16 level stack 
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Note that there are several simplifications in this particular program. First, 
there are no checks for invalid file names which could, for example, contain 
ambiguous references. This situation could be detected by scanning the 32 
byte default area starting at location 005CH for ASCII question marks. A 
check should also be made to ensure that the file names have, in fact, been 
included (check locations 005DH and 006DH for non-blank ASCII 
characters). Finally, a check should be made to ensure that the source and 
destination file names are different. A speed improvement could be made by 
buffering more data on each read operation. One could, for example, 
determine the size of memory by fetching FBASE from location 0006H and 
use the entire remaining portion of memory for a data buffer. In this case, the 
programmer simply resets the DMA address to the next successive 128 byte 
area before each read. Upon writing to the destination file, the DMA address 
is reset to the beginning of the buffer and incremented by 128 bytes to the end 
as each record is transferred to the destination file. 

Sample File Dump Utility. 

The file dump program shown below is sHghtly more complex than the single 
copy program given in the previous section. The dump program reads an 
input file, specified in the CCP command hne, and displays the content of 
each record in hexadecimal format at the console. Note that the dump 
program saves the CCP's stack upon entry, resets the stack to a local area, 
and restores the CCP's stack before returning directly to the CCP. Thus, the 
dump program does not perform warm start at the end of processing. 

; DUMP program reads input file and displays hex data 



0100 




org 




100h 




KJ005 = 


bdos 


equ 




005h 


;dos entry point 


0001 = 


cons 


equ 




1 


;read console 


0002 = 


typef 


equ 




2 


;type function 


0009 = 


printf 


equ 




9 


;buffer print entry 


000b = 


brkf 


equ 




11 


;break key function {true if char 


000f = 


openf 


equ 




15 


; f ile open 


0014 - 


readf 


equ 




20 


;read function 


005c = 


fcb 


equ 




5ch 


;file control block address 


0080 = 


buff 


equ 




80h 


;input disk buffer address 




'. 


non 


graphic characters 


000d = 


cr 


equ 




0dh 


^carriage return 


00a = 


If 


equ 




0ah 


;line feed 




' 


file 


> control block definitions 


005c = 


fcbdn 


equ 




fcb+0 


;disk name 


005d = 


fcbfn 


equ 




fcb+1 


;file name 


0065 = 


fcbf t 


equ 




fcb+9 


;disk file type (3 characters) 


0068 = 


fcbrl 


equ 




fcb+12 


;file's current reel number 


006b = 


fcbrc 


equ 




fcb+1 5 


;file's record count (0 to 128) 


007c = 


fcbcr 


equ 




fcb+32 


;current (next) record number (0 


007d = 


fcbln 


equ 




fcb+33 


;fcb length 




1 


set 


up 


stack 




0100 210000 


1 


Ixi 




h,0 




0103 39 




dad 




sp 





entry stack pointer in hi from the ccp 
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0X04 221502 

0107 315702 

010a cdcl01 
O10d feff 
010f c21b01 



0112 llf301 
0115 cd9c01 
0118 C35101 



011b 3e80 
011d 321302 

0120 210000 



openok: 



0123 eS 

0124 cda201 

0127 el 

0128 da5101 
012b 47 



012c 7d 
012d e60f 
012f C24401 

0132 cd7201 



0135 cd5901 

0138 0f 

0139 da5101 

013c 7c 
013d cd8f01 

0140 7d 

0141 cd8f01 

0144 23 

0145 3e20 
0147 cd6501 
014a 7 8 
014b cddf01 
014e C32301 



gloop: 



nonum: 



finis: 



0151 cd7201 
0154 2al502 

0157 f9 

0158 c9 



shld oldsp 

set sp to local stack area (restored at finis) 

Ixi sp.stktop 

read and print successive buffers 

call setup ;set up input file 

cpi 255 ;255 if file not present 

jnz openok jskip if open is ok 

file not there, give error n»essage and return 

Ixi d,opninsg 

call err 

3inp finis ;to return 

;open operation ok, set buffer index to end 

mvl a,80h 

sta ibp ;set buffer pointer to 80h 

hi contains next address to print 

1x1 h,0 ;start with 0000 



push h ;save line position 

call gnb 

pop h ;recall line position 

jc finis ;carrysetbygnbifendfile 

mov b,a 

print hex values 

check for line fold 

mov a , 1 

ani 0fh ;check low 4 bits 

jnz nonum 

print line number 

call crlf 

check for break key 

call break 

accum Isb = 1 if character ready 

rrc ; into carry 

jc finis ;don*t print any more 



mov 


a,h 


call 


phex 


mov 


a,l 


call 


phex 


inx 


h 


mvi 


fit 


call 


pchar 


mov 


a,b 


call 


phex 


jmp 


gloop 



;to next line number 



end of dump, return to ccp 

(note that a jmp to 0000h reboots) 

call crlf 

Ihld oldsp 

sphl 

stack pointer contains ccp's stack location 

ret ;to the ccp 



subroutines 



0159 e5d5c5 
015c 0e0b 
015e cd0500 
0161 cldlel 
0164 c9 



break: ;check break key (actually any key will do) 
push h! push d! push b; environment saved 
mvi cbrkf 
call bdos 

pop bi pop d! pop h; environment restored 
ret 

7 

pchar: ;print a character 
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0165 e5d5c5 
0168 0e02 
016a Sf 
016b cd0S00 
016e cldlel 
0171 c9 



0X72 3e0d 
0174 cd6501 
0177 3e0a 
0179 cd6501 
017c c9 



crlf ! 



pnib: 



017d e60f 
017f £e0a 
0181 d2B901 

0184 c630 
0186 c38b01 



0189 c637 pl0: 
018b cd6S01 prn: 
018e c9 



018£ 
0190 
0191 
0192 
0193 
0194 
0197 
0198 
019b 


£5 

0£ 

0£ 

0£ 

0£ 

cd7d01 

fl 

cd7d01 

c9 


019c 
019e 
01al 


e 

0e09 

cd0500 

c9 

; 


01a2 
01aS 
01a7 


9 

3al302 
fe80 
c2b301 


01aa 
01ad 
01ae 


cdce01 

b7 

cab301 


01bl 
01b2 


37 
c9 

r 


01b3 
01b4 
01b6 
01b7 


g 

5f 

1600 
3c 
321302 


01ba 
01bd 


; 

218000 
19 


01be 


7e 



phex : 



ere: 



gnb: 



push h! push dl push b; saved 

mvi c,typef 

mov e,a 

call bdos 

pop b! pop dl pop h; restored 

ret 



mvi 


a,cr 


call 


pchar 


mvi 


a, If 


call 


pchar 


ret 




yprint 


nibble in reg a 


ani 


0£h ;low 4 bits 


cpi 


10 


jnc 


Dl0 


less than or equal to 9 


adi 


•0' 


jmp 


prn 


greater 


or equal to 10 


adi 


•a» - 10 


call 


pchar 


ret 




;print 


hex char in reg a 


push 


psw 


rrc 




rrc 




rrc 




rrc 




call 


pnib yprint nibb 


pop 


psw 


call 


pnib 


ret 





;print error message 

d,e addresses message ending with **$- 

mvi c,printf rprint buffer function 

call bdos 

ret 



?get next byte 

Ida ibp 

cpi 80h 

jnz g0 

read another buffer 



call diskr 

ora a ;zero value if read ok 

jz g0 ;for another byte 

end of data, return with carry set for eof 

stc 

ret 

;read the byte at buff-i-reg a 

mov e,a ;ls byte of buffer index 

mvi d,0 ;double precision index to de 

inr a ; index ° index -fl 

sta ibp ;back to memory 

pointer is incremented 

save the current file address 

Ixi h,buff 

dad d 

absolute character address is in hi 

mov a«m 
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f 


byte 


is in the accumulator 


01bf 


b7 




ora 


a 


; reset carry bit 


01c0 


c9 




ret 










setup: 


;set 


up file 








; 


open 


the file for input 


01cl 


af 




xra 


a 


; zero to accum 


01c2 


327C00 




sta 


fcbcr 


;clear current r 


01c5 


115C00 


* 


Ixi 


d,fcb 




01c8 


0e0£ 




mvi 


c,openf 




01ca 


cd0500 




call 


bdos 








; 


255 : 


In accum if 


open error 


01cd 


c9 




ret 










diskr: 


;read disk file 


record 


01ce 


e5d5c5 




push 


hi push d! 


push b 


01dl 


115C00 




Ixi 


d.fcb 




01d4 


0el4 




mvi 


creadf 




01d6 


cd0500 




call 


bdos 




01d9 


cldlel 




pop 1 


D I pop ■ 1 pop h 


01dc 


c9 




ret 







; fixed message area 
Idd 46494c0si9non: db 'file du p version 2.0$' 
01f3 0d0a4e0opnmsg: db cr,lf,'no input file present on disk$* 

; var iable area 
0213 ibp: ds 2 ; input buffer pointer 
0215 oldsp: ds 2 ;entry sp value from ccp 

; stack area 
0217 ds 64 ;reserve 32 level stack 

stktop: 

0257 ' end 

Sample Random Access Program. 

This manual is concluded with a rather extensive, but complete example of 
random access operation. The program listed below performs the simple 
function of reading or writing random records upon command from the 
terminal. Given that the program has been created, assembled, and placed 
into a file labelled RAND0M.COM, the CCP level command: 

RANDOM X.DAT 

starts the test program. The program looks for a file by the name X.DAT (in 
this particular case) and, if found, proceeds to prompt the console for input. 
If not found, the file is created before the prompt is given. Each prompt takes 
the form 

next command? 

and is followed by operator input, terminated by a carriage return. The input 
commands take the form 

nW nR Q 
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where n is an integer value in the range to 65535, and W, R, and Q are simple 
command characters corresponding to random write, random read, and quit 
processing, respectively. If the W command is issued, the RANDOM 
program issues the prompt 

type data: 

The operator then responds by typing up to 127 characters, followed by a 
carriage return. RANDOM then writes the character string into the X.D AT 
file at record n. If the R command is issued, RANDOM reads record number 
n and displays the string value at the console. If the Q command is issued, the 
X.DAT file is closed, and the program returns to the console command 
processor. In the interest of brevity, the only error message is 

error, try again 



The program begins with an initialization section where the input file is 
opened or created, followed by a continuous loop at the label "ready" where 
the individual commands are interpreted. The default file control block at 
005CH and the default buffer at 0080H are used in all disk operations. The 
utility subroutines then follow, which contain the principal input line 
processor, called "readc!' This particular program shows the elements of 
random access processing, and can be used as the basis for further program 
development. 

sample random access program for cp/m 2.0 
0100 org. 100h ;base of tpa 



0000 


8 


reboot 


equ 


0000h 


;system reboot 


0005 


S 


bdos 


equ 


0005h 


;bdos entry point 


0001 


S 


i 
coninp 


equ 


1 


;console input function 


0002 


= 


conout 


equ 


2 


;console output function 


0009 


= 


pstring 


equ 


9 


;print string until '$' 


000a 


= 


rstring 


equ 


10 


;read console buffer 


000c 


S 


version 


equ 


12 


;return version number 


000f 


= 


openf 


equ 


15 


;file open function 


0010 


=* 


closef 


equ 


16 


;close function 


0016 


s 


makef 


equ 


22 


;make file function 


0021 


= 


readr 


equ 


33 


;read random 


0022 


= 


writer 


equ 


34 


; write random 


005c 


s 


fcb 


equ 


005ch 


;default file control bl 


007d 


= 


ranrec 


equ 


fcb-i-33 


;random record position 


007f 


= 


ranovf 


equ 


fcb+35 


;high order (overflow) b^ 


0080 


- 


buff 


equ 


00d0h 


;butfer address 


000d 


= 


cr 


equ 


0dh 


;carriage return 


000a 


= 


If 


equ 


0dh 


;line feed 



******************************** «**«««^«^^^«^,^^,^^^ 

* load SP, set-up file for random access • 
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0100 31bc0 



Ixi 



sp, stack 



0103 0e0c 
0105 cd050 
0108 fe20 
010d d2160 

010d nib0 
0110 cdda0 
0U3 C3000 



version 2. 0? 

mvi c, version 

call bdos 

cpi 2flh ;version 2.0 or better? 

jnc versok 

bad version, message and go back 

Ixi d,badver 

call print 

jmp reboot 



versok : 



0116 0e0£ 

0118 115c0 

011b cd050 

011e 3c 

011f C2370 

0122 0el6 
0124 il5c0 
0127 cd050 
012a 3c 
012b C2370 



012e 113a0 
0131 cdda0 
0134 C3000 



0137 cde50 
013a 2 2 7d0 
J13d 217f0 
0140 3600 
.)142 fe3l 
0144 C2560 



J147 tiel0 

0149 115C0 
0i4c cd030 
014f 3c 

0150 cab90 
0153 C30O0 



correct version for random access 

mvi copenf ;open default fcb 

Ixi d,fcb 

call bdos 

inr a ;err 255 oecomes zero 

jnz ready 

cannot open file, so create it 

mvi c,makef 

Ixi d,fcb 

call bdos 

inr a ;err 255 becomes zero 

jnz ready 

cannot create file, directory full 

Ixi d,nospace 

call print 

jmp reboot ;back to ccp 

*************************************************** 

* loop back to "ready" after each command * 

* * 

ready: 

; file is ready for processing 

call readcom ;read next command 

shld ranrec ;store input record! 

Ixi h,ranovf 

n»vi m,0 ;clearhighbyteifset 

cpi 'Q* ;quit? 

jnz notq 

quit processing, close file 

mvi cclosef 

Ixi d,fcb 

call bdos 

inr a ;err255 becomes 

jz error ;error message, retry 

jmp reboot ;back to ccp 

end of quit command, process write * 



0156 fe57 
0158 C2890 



015b 114d0 
015e cdda0 
0161 0e7f 
0163 21800 



notq: 

; not the auit command, random write? 

cpi 'W 

]nz notw 

; this IS a random write, fill buffer until cr 

Ixi d,datmsg 

call print ;data prompt 

mvi c,127 ;up to 127 characters 

Ixi h,buff .'destination 
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rloop: ;read next character to buff 



push 


b 


;save counter 


push 


h 


;next destination 


call 


aetchr 


;character to a 


pop 


h 


; restore counter 


pop 


b 


;restore next to fill 


cpi 


cr 


;end of line? 


J2 


e rloop 




not end 


, store 


character 


mov 


m,a 




inx 


h 


;next to fill 


dcr 


c 


;counter goes down 


jnz 


rloop 


;end of buffer? 



mvi 


c, writer 


Ixi 


d.fcb 


call 


bdos 


ora 


a 


]nz 


error 


3mp 


ready 



0166 c5 

0167 e5 

0168 cdc20 
016b el 
016c cl 
016d fe0d 
016f ca780 

0172 77 

0173 23 

0174 0d 

0175 C2660 

e rloop: 

; end of read loop, store 00 
0178 3600 mvi ro,0 

7 

; write the record to selected record number 
017a 0e22 
017c 115C0 
017f cd030 

0182 b7 ora a ;error code zero? 

0183 c2b90 jnz error ?message if not 
0186 C3370 jmp ready ;for another record 

;* * 

;♦ end of write command, process read * 

;* * 

notw: 

; not a write command, read record? 

0189 fe52 cpi 'R' 

016b c2b90 jnz error ;skip if not 

; read random record 

018e 0e21 mvi creadr 

0190 115C0 Ixi d,fcb 
0193 cd050 call bdos 

®1^^ ^7 ora a ;return code 00? 

0197 c2b90 jnz error 

; read was successful, write to console 

019a cdcf0 call crlf ;new line 

019d 0e80 mvi c,128 ;max 128 characters 

019f 21800 Ixi h,buff ;next to get 

wloop: 

01a2 7e mov a,m ;next character 

01a3 23 inx h ynext to get 

01a4 e67f ani 7fh ;mask parity 

01a6 ca370 jz read/ ; for another command if 00 

01a9 c5 push b ;save counter 

01aa e5 push h jsave next to get 

01ab fe20 cpi ' ' jgraphic? 

01ad d4c80 cnc putchr ;skip output if not 

01b0 el pop h 

01bl cl pop b 

01b2 0d dcr c ;count=count-l 

01b3 c2a20 jnz wloop 

01b6 C3370 ^ jmp ready 

. * * 

;* end of read command, all errors end-up here * 

_ * * 



error: 

01b9 11590 Ixi d,errmsg 

01bc cdda0 call print 

01bfc3370 jmp ready 
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; * * 

;* Utility subroutines for console i/o * 

;* * 

getchr; 

;read next console character to a 

01c2 0e01 mvi c,coninp 

01c4 cd050 call bdos 

eic7 c9 ret 

putchr : 

;write character from a to console 

01c8 0602 mvi cconout 

01ca 5f mov e,a ;character to send 

Olcb cd050 call bdos ;send character 

01ce c9 ret 

crlf : 

;send carriage return line feed 

01cf 3e0d mvi a,cr ycarriage return 

01dl cdc80 call putchr 

01d4 3e0a mvi a, If ;line feed 

01d6 cdc80 call putchr 

01d9 c9 ret 

print: 

;print the buffer addressed by de until $ 

01da dS push d 

01db cdcf0 call crlf 

01de dl pop d ; new line 

01df 0e09 mvi c,pstring 

01el cd050 call bdos ;print the string 

01e4 c9 ret 

readcom: 

;read the next command line to the conbuf 

01e5 116b0 Ixi d, prompt 

01e8 cddaB call print ;command? 

01eb 0e0a mvi crstring 

01ed 117a0 Ixi d, conbuf 

01f0 cd050 call bdos ;read command line 

; command line is present, scan it 

01f3 21000 Ixi h,0 ;start with 0000 

01f6 117c0 Ixi d,conlin;command line 

01f9 la readc: Idax d ;next command character 

01fa 13 inx d ; to next command position 

01fb b7 ora a ;cannot be end of command 

01fc c8 rz 

; not; zero, numeric? 

01fd d630 sui '0* 

01ff fe0a cpi 10 ;carry if numeric 

0201 d2130 jnc endrd 

; add-in next digit 

0204 29 dad h ;*2 

0205 4d mov c,l 

0206 44 mov b,h ; be = value * 2 

0207 29 dad h ; *4 

0208 29 dad h ;*8 

0209 09 dad b ;*2 + *8 « *10 
020a 85 .. add 1 ;+digit 

020b 6f mov l,a 

020c d2f90 jnc readc ;for another char 

020f 24 inr h ;overflow 

0210 c3f90 jmp readc ;for another char 

endrd: 

; end of read, restore value in a 

«213 C630 adi •0' jcommand 

0215 fe61 cpi 'a' rtranslate case? 
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0217 d8 re 

lower case, mask lower case bits 

0218 e65f ani 101$llllb 
021a c9 ret 

*************************************************** 

* * 

* string data area for console messages * 

* « 

badver: 



021b 


536f79 




db 


•sorry, you need cp/m version 2$' 


023a 
24d 


nospace 
4e6f29 

datinsg : 
547970 


: 
db 

db 


•no directory spaceS* 
* type data: $' 


0259 


er rmsg : 
457272 


db 


•error, try again. $' 


26b 


prompt: 
4e6570 


db 


•next command? $' 






t 
t * 






* fixed and 
I * 


variable data area * 








027a 


21 conbuf: 


db 


conlen ;length of console buffer 


027b 
027c 
0021 


consiz: 
conlin: 
= conlen 


ds 
ds 
equ 


1 ;resulting size after read 
32 ;length 32 buffer 
$-consiz 


029c 


stack: 


ds 


32 ;16 level stack 


2bc 






end 





Again, major improvements could be made to this particular program to 
enhance its operation. In fact, with some work, this program could evolve 
into a simple data base management system. One could, for example, assume 
a standard record size of 128 bytes, consisting of arbitrary fields within the 
record. A program, called GETKEY, could be developed which first reads a 
sequential file and extracts a specific field defined by the operator. For 
example, the command 

GETKEY NAMES.DAT LASTNAME 10 20 

would cause GETKEY to read the data base file NAMES.DAT and extract 
the "LASTNAME" field from each record, starting at position 10 and ending 
at character 20. GETKEY builds a table in memory consisting of each 
particular LASTNAME field, along with its 16-bit record number location 
within the file. The GETKEY program then sorts this list, and writes a new 
file, called LASTNAME.KEY, which is an alphabetical hst of LASTNAME 
fields with their corresponding record numbers. (This list is called an 
"inverted index" in information retrieval parlance.) 

Rename the program shown above as QUERY, and massage it a bit so that 
it reads a sorted key file into memory. The command line might appear as: 



QUERY NAMES.DAT LASTNAME.KEY 
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Instead of reading a number, the QUERY program reads an alphanumeric 
string which is a particular key to find in the NAMES.DAT data base. Since 
the LASTNAME.KEY list is sorted, you can find a particular entry quite 
rapidly by performing a "binary searchl' similar to looking up a name in the 
telephone book. That is, starting at both ends of the list, you examine the 
entry halfway in between and, if not matched, split either the upper half or 
the lower half for the next search. You'll quickly reach the item you're 
looking for (in log2(n) steps) where you'll find the corresponding record 
number. Fetch and display this record at the console, just as we have done in 
the program shown above. 

At this point you're just getting started. With a httle more work, you can 
allow a fixed grouping size which differs from the 128 byte record shown 
above. This is accomplished by keeping track of the record number as well as 
the byte offset within the record. Knowing the group size, you randomly 
access the record containing the proper group, offset to the beginning of the 
group within the record read sequentially until the group size has been 
exhausted. 

Finally, you can improve QUERY considerably by allowing boolean 
expressions which compute the set of records which satisfy several 
relationships, such as a LASTNAME between HARDY and LAUREL, and 
an AGE less than 45. Display all the records which fit this description. 
Finally, if your lists are getting too big to fit into memory, randomly access 
your key files from the disk as well. One note of consolation after all this 
work: if you make it through the project, you'll have no more need for this 
manual! 
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System Function Summary 



FUNC FUNCTION NAME 



INPUT OUTPUT 

PARAMETERS RESUUTS 






System Reset 


none 


none 


1 


Console Input 


none 


A = char 


2 


Console Output 


E=char 


none 


3 


Reader Input 


none 


A = char 


4 


Punch Output 


E = char 


none 


5 


List Output 


E=char 


none 


6 


Direct Console I/O 


seedef 


seedef 


7 


Get I/O Byte 


none 


A=IOBYTE 


8 


Set I/O Byte 


E=IOBYTE 


none 


9 


Print String 


DE = . Buffer 


none 


10 


Read Console Buffer 


DE = . Buffer 


seedef 


11 


Get Console Status 


none 


A = 00/FF 


12 


Return Version Number 


none 


HL= Version* 


13 


Reset Disk System 


none 


seedef 


14 


Select Disk 


E = Disk Number 


seedef 


15 


Open File 


DE = .FCB 


A = DirCode 


16 


Close File 


DE = .FCB 


A = DirCode 


17 


Search for First 


DE = .FCB 


A = DirCode 


18 


Search for Next 


none 


A = DirCode 


19 


Delete File 


DE = .FCB 


A = DirCode 


20 


Read Sequential 


DE = .FCB 


A = Err Code 


21 


Write Sequential 


DE = .FCB 


A = Err Code 


22 


Make File 


DE = .FCB 


A = DirCode 


23 


Rename File 


DE = .FCB 


A = DirCode 


24 


Return Login Vector 


none 


HL = Login Vect* 


25 


Return Current Disk 


none 


A = Cur Disk # 


26 


Set DMA Address 


DE = .DMA 


none 


27 


Get Addr(Alloc) 


none 


HL = . Alloc 


28 


Write Protect Disk 


none 


seedef 


29 


Get R/0 Vector 


none 


HL=R/OVect* 


30 


Set File Attributes 


DE = .FCB 


see def 


31 


Get Addr (disk parms) 


none 


HL=.DPB 


32 


Set/Get User Code 


seedef 


seedef 


33 


Read Random 


DE = .FCB 


A = Err Code 


34 


Write Random 


DE = .FCB 


A = Err Code 


35 


Compute File Size 


DE = .FCB 


rO, rl, r2 


36 


Set Random Record 


DE = .FCB 


rO, rl, r2 



*Note that A = L, and B = H upon return 
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Introduction to ED 

ED is the context editor for CP/M, and is used to create and alter CP/M 
source files. ED is initiated in CP/M by typing 

{(filename) 
< filename) '(filetype) 

In general, ED reads segments of the source file given by (filename) or 
(filename) • (filetype) into central memory, where the file is manipulated by 
the operator, and subsequently written back to disk after alterations. If the 
source file does not exist before editing, it is created by ED and initialized to 
empty. The overall operation of ED is shown in Figure 1. 

ED Operation 

ED operates upon the source file, denoted in Figure 1 by x.y, and passes all 
text through a memory buffer where the text can be viewed or altered (the 
number of lines which can be maintained in the memory buffer varies with 
the Hne length, but has a total capacity of about 6000 characters in a 16K 
CP/M system). Text material which has been edited is written onto a 
temporary work file under command of the operator. Upon termination of 
the edit, the memory buffer is written to the temporary file, followed by any 
remaining (unread) text in the source file. The name of the original file is 
changed from x.y to x.BAK so that the most recent previously edited source 
file can be reclaimed if necessary (see the CP/M commands ERASE and 
RENAME). The temporary file is changed from x.$$$ to x.y which becomes 
the resulting edited file. 

The memory buffer is logically between the source file and working file as 
shown in Figure 2. 

Text Transfer Functions 

Given that n is an integer value in the range through 65535, the following 
ED commands transfer lines of text from the source file through the memory 
buffer to the temporary (and eventually final) file: 
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Figure 1. Overall ED Operation 




Source 
Libraries 




Note: the ED program accepts both lower and upper case ASCII characters 
as input from the console. Single letter commands can be typed in either case. 
The U command can be issued to cause ED to translate lower case 
alphabetics to upper case as characters are filled to the memory buffer from 
the console. Characters are echoed as typed without translation, however. 
The -U command causes ED to revert to "no translation" mode. ED starts 
with an assumed -U in effect. 
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Figure 2. Memory Buffer Organization 
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nA<cr> * Append the next n unprocessed source lines from the source 
file at SP to the end of the memory buffer at MR Increment 
SP and MP by n. 

nW<cr> Write the first n lines of the memory buffer to the temporary 
file free space. Shift the remaining lines n + 1 through MP to 
the top of the memory buffer. Increment TP by n. 

E<cr> End the edit. Copy all buffered text to temporary file, and 

copy all unprocessed source hnes to the temporary file. 
Rename files as described previously. 

H<cr) Move to head of new file by performing automatic E 

command. Temporary file becomes the new source file, the 
memory buffer is emptied, and a new temporary file is created 
(equivalent to issuing an E command, followed by a 
rein vocation of ED using x.y as the file to edit). 

0<cr> Return to original file. The memory buffer is emptied, the 

temporary file is deleted, and the SP is returned to position 1 
of the source file. The effects of the previous editing 
commands are thus nullified. 

Q<cr> Quit edit with no file alterations, return to CP/M. 

There are a number of special cases to consider. If the integer n is omitted in 
any ED command where an integer is allowed, then 1 is assumed. Thus, the 
commands A and W append one line and write 1 line, respectively. In 
addition, if a pound sign ( # ) is given in the place of n, then the integer 65535 
is assumed (the largest value for n which is allowed). Since most reasonably 
sized source files can be contained entirely in the memory buffer, the 
command # A is often issued at the beginning of the edit to read the entire 
source file to memory. Similarly, the command # W writes the entire buffer 
to the temporary file. Two special forms of the A and W commands are 
provided as a convenience. The command OA fills the current memory buffer 
to at least half-full, while OW writes lines until the buffer is at least half 
empty. It should also be noted that an error is issued if the memory buffer size 
is exceded. The operator may then enter any command (such as W) which 
does not increase memory requirements. The remainder of any partial line 
read during the overflow will be brought into memory on the next successful 
append. 



•<cr> represents the carriage-return key 
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Memory Buffer Organization 

The memory buffer can be considered a sequence of source lines brought in 
vyith the A command from a source file. The memory buffer has an associated 
(imaginary) character pointer (CP) which moves throughout the memory 
buffer under command of the operator. The memory buffer appears logically 
as shown in Figure 3 where the dashes represen t characters of the source line 
of indefinite length, terminated by carriage return ((cr> ) and Une feed «lf> ) 
characters, and c^ represents the imaginary character pointer. Note that the 
CP is always located ahead of the first character of the first line, behind the 
last character of the last line, or between two characters. The current line CL 
is the source line which contains the CP. 

Memory Buffer Operation 

Upon initiation of ED, the memory buffer is empty (i.e., CP is both ahead and 
behind the first and last character). The operator may either append lines (A 
command) from the source file, or enter the lines directly from the console 
with the insert command 

I<cr> 

ED then accepts any number of input lines, where each line terminates with 
a <cr> (the (If) i§ supplied automatically), until a control-z (denoted by tz) 
is typed by the operator. The CP is positioned after the last character 
entered. The sequence 

I<cr> 

NOW IS THE<cr> 

TIME FOR<cr> 

ALL GOOD MEN<cr> 

Tz 

leaves the memory buffer as shown below 

NOWISTHE<cr><10 

TIMEFOR<cr><10 

ALL GOOD MEN<cr><lf> A 

Various commands can then be issued which manipulate the CP or display 
source text in the vicinity of the CP. The commands shown below with a 
preceding n indicate that an optional unsigned value can be specified. When 
preceded by ± , the command can be unsigned, or have an optional preceding 
plus or minus sign. As before, the pound sign ( # ) is replaced by 65535. If an 
integer n is optional, but not supplied, then n = 1 is assumed. Finally, if a plus 
sign is optional, but none is specified, then + is assumed. 
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± B<cr> move CP to beginning of memory buffer if + , and to bottom 
if-. 

±nC<cr> move CP by ±n characters (toward front of buffer if + ), 
counting the (cr><lf> as two distinct characters. 

± nD<cr> delete n characters ahead of CP if plus and behind CP if 
minus. 

±nK(cr> kill (i.e. remove) ±n lines of source text using CP as the 
current reference. If CP is not at the beginning of the current 
line when K is issued, then the characters before CP remain 
if + is specified, while the characters after CP remain if - is 
given in the command. 

± nL<cr> if n = 0, move CP to the beginning of the current line (if it is 
not abready there). If n =^0, first move the CP to the begmning 
of the current line, and then move it to the beginning of the 
line which is n lines down (if + ) or up (if -). The CP will stop 
at the top or bottom of the memory buffer if too large a value 
is specified. 

± nT<cr> If n = then type the contents of the current line up to CP. If 
n = 1 then type the contents of the current line from CP to the 
end of the line. If n> 1 then type the current line along with 
n-1 lines which follow, if + is specified. Similarly, if n>l and 
- is given, type the previous n lines, up to the CP. The break 
key can be depressed to abort long type-outs. 

± n<cr) equivalent to ± nLT, which moves up or down and types a 
single line. 



Command Strings 

Any number of commands can be typed contiguously (up to the capacity of 
the CP/M console buffer), and are executed only after the <cr> is typed. 
Thus, the operator may use the CP/M console command functions to 
manipulate the input command. 

Rubout remove the last character 

Control-X delete the entire line 

Control-C re-initialize the CP/M System 
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Control-E return carriage for long lines without transmitting buffer 
(max 128 chars) 

Suppose the memory buffer contains the characters shown in the previous 
section, with the CP following the last character of the buffer. The command 
strings shown below produce the results shown to the right. 



Command String Effect 



Resulting Memory Buffer 



B2T<cr> 



move to beginning of 
buffer and type 2 lines: 
"NOW IS THE 
TIME FOR" 



ctNOWISTHE<cr><lf> 
TIMEFOR<cr><lf> 
ALL GOOD MEN<cr><10 



5C0T<cr> move CP 5 characters and NOW I ^ S THE <cr><lf> 

type the beginning of the 
line "NOW I" 

2L-T<cr> move two lines down and NOW IS THE <cr><10 

type previous line TIME FOR<cr><lf> 

"TIME FOR" c^ ALL GOOD MEN<cr><10 

-L#K<cr> move up one line, delete NOW IS THE<cr><lf> ^ 

65535 lines which follow 



I<cr> 


insert two lines 


NOWISTHE<cr><lf> 


TIME TO<cr> 


of text 


TIME TO<cr><lf) 


INSERT<cr> 
tz 




INSERT<cr><lf>A 



-2L#T<cr> move up two lines, and typeNOW IS THE<cr><lf> ^ 

65535 hnes ahead of CP TIME TO<cr><lf> 
"NOW IS THE" INSERT<cr><10 



(cr) 



move down one line 
and type one line 
"INSERT" 



NOWISTHE<cr><lO 

TIMETO<cr><10ct 
INSERT <cr><l£> 
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Text Search and Alteration 

ED also has a command which locates strings within the memory buffer. The 
command takes the form 



nF C1C2 . 



■c.{t>} 



where Cj through c^ represent the characters to match followed by either a 
(cr> or control -z.* ED starts at the current position of CP and attempts to 
match all k characters. The match is attempted n times, and if successful, the 
CP is moved directly after the character c^. If the n matches are not 
successful, the CP is not moved from its initial position. Search strings can 
include tl (control-1), which is replaced by the pair of symbols <cr> <lf>. 

The following commands illustrate the use of the F command: 
Command String Effect Resulting Memory Buffer 

B#T<cr> move to beginning c^NOW IS THE <cr><lf> 

and type entire TIME FOR<cr><lf> 

buffer ALL GOOD MEN<cr><lf> 

FST<cr> find the end of NOW ISTe^HE<cr><lf> 

the string "S T" 

FITzOTT find the next "I" and type NOW IS THE<cr><lf> 

to the CP then type the T^ME FOR<cr><10 

remainder of the current ALL GOOD MEN<cr><10 
line: "TIME FOR" 

An abbreviated form of the insert -command is also allowed, which is often 
used in conjunction with the F command to make simple textual changes. 
The form is: 

IciC2...Cntz or 
I C1C2 . . . Cn<cr> 

where Cj through Cn are characters to insert. If the insertion string is 
terminated by a tz, the characters Ci through Cp are inserted directly 
following the CP, and the CP is moved directly after character c^. The action 
is the same if the command is followed by a <cr> except that a <cr)<lf> is 
automatically inserted into the text following character Cn. Consider the 
following command sequences as examples of the F and I commands: 



*The control-z is used if additional commands will be typed following the tz. 
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Command String 



Effect 



BITHIS IS T z<cr> 

Insert "THIS IS' 
at the beginning 
of the text 



Resulting Memory Buffer 

THIS IS c^ NOW THE<cr><l£> 
TIME FOR <cr><lf> 
ALL GOOD MEN<cr><lf> 



FTIMETz-4DIPLACEtz<cr> 

find "TIME" and delete 
it; then insert "PLACE" 



THIS IS NOW THE<cr><lf> 
PLACE e4F0R<cr><lf> 
ALL GOOD MEN<cr><lf> 



3F0Tz-3D5DICHANGEST<cr> THIS IS NOW THE<cr><lf> 

find third occurrence of PLACE FOR<cr><lf> 
"0" (i.e. the second "0" in ALL CHANGES c^ <cr><lf> 
GOOD), delete previous 3 
characters; then insert 
"CHANGES" 



-8CIS0URCE<cr> 



move back 8 characters 
and insert the line 
"SOURCE<cr><lf>" 



THIS IS NOW THE<cr><lf> 
PLACE FOR<cr><lf> 
ALL SOURCE<cr><lf> 
c^CHANGES<cr><lf> 



ED also provides a single command which combines the F and I commands 
to perform simple string substitutions. The command takes the form 



n SciC2 . . .CkTzdid2. . . d^ 



{t>} 



and has exactly the same effect as applying the command string 

FciC2...Cktz-kDIdid2...d^ |<f^>l 

a total of n times. That is, ED searches the memory buffer starting at the 
current position of CP and successively substitutes the second string for the 
first string until the end of buffer, or until the substitution has been 
performed n times. 

As a convenience, a command similar to F is provided by ED which 
automatically appends and writes lines as the search proceeds. The form is 



nNc,C2...c,|<f;>| 
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which searches the entire source file for the nth occurrence of the string C1C2 
. . . Ck (recall that F fails if the string cannot be found in the current buffer). 
The operation of the N command is precisely the same as F except in the case 
that the string cannot be found within the current memory buffer. In this 
case, the entire memory contents is written (i.e., an automatic # W is issued). 
Input lines are then read until the buffer is at least half full, or the entire 
source file is exhausted. The search continues in this manner until the string 
has been found n times, or until the source file has been completely 
transferred to the temporary file. 

A final line editing function, called the juxtaposition command takes the 
form 

nJciC2...Cktz didg.-.dmtz eie2 . . . e^ j ^J^^^ | 

with the following action applied n times to the memory buffer: search from 
the current CP for the next occurrence of the string C1C2. . .Ck.Iffound,insert 
the string di,d2 . . .,dm, and move CP to follow d^. Then delete all characters 
following CP up to (but not including) the string ei, e2, . . . eq, leaving CP 
directly after d^. If ei, eg, . . . eq cannot be found, then no deletion is made. If 
the current hne is 

e^NOW ISTHETIME<cr><lf> 

Then the command 

JWT2WHATtzTl<cr> 

Results in 

NOW WHAT e^<cr><10 

(Recall that tl represents the pair <cr><lf> in search and substitution 
strings). 

It should be noted that the number of characters allowed by ED in the F. S, 
N, and J commands is limited to 100 symbols. 



Source Libraries 

ED also allows the inclusion of source libraries during the editing process 
with the R command. The form of this command is 
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Rfif2..fntz or 

Rfif2.,fn<cr> 

where f if2 . . fn is the name of a source file on the disk with an assumed file type 
of *LIB! ED reads the specified file, and places the characters into the 
memory buffer after CP, in a manner similar to the I command. Thus, if the 
command 

RMACRO<cr> 

is issued by the operator, ED reads from the file MACRO. LIB until the 
end-of-file, and automatically inserts the characters into the memory buffer. 

Repetitive Command Execution 

The macro command M allows the ED user to group ED commands together 
for repeated evaluation. The M command takes the form: 



n M C1C2 . 



c.{t>} 



where C1C2 . . . c^ represent a string of ED commands, not including another 
M command. ED executes the command string n times if n>l. If n = or 1, the 
command string is executed repetitively until an error condition is 
encountered (e.g., the end of the memory buffer is reached with an F 
command). 

As an example, the following macro changes all occurrences of GAMMA to 
DELTA within the current buffer, and types each line which is changed: 

MFGAMMATz-5DIDELTATzOTT<cr> 

or equivalently 

MSGAMMATzDELTATzOTT<cr> 



ED Error Conditions 

.1 error conditions, ED prints the last character read before the error, along 
with an error indicator: 

? unrecognized command 
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> memory buffer full (use one of the commands D, K, N, S, or 
W to remove characters), F, N, or S strings too long. 

# cannot apply command thenumber of times specified (e.g., in 
F command) 

cannot open LIB file in R command 

Cyclic redundancy check (CRC) information is written with each output 
record under CP/M in order to detect errors on subsequent read operations. 
If a CRC error is detected, CP/M will type 

PERM ERR DISK d 

where d is the currently selected drive (A, B, . . .). The operator can choose 
to ignore the error by typing any character at the console (in this case, the 
memory buffer data should be examined to see if it was incorrectly read), or 
the user can reset the system and reclaim the backup file, if it exists. The file 
can be reclaimed by first typing the contents of the BAK file to ensure that 
it contains the proper information: 

TYPE x.BAK<cr> 

where x is the file being edited. Then remove the primary file: 

ERA x.y<cr> 

and rename the BAK file: 

RENx.y = x.BAK<cr> 

The file can then be re-edited, starting with the previous version. 

Summary of Control Characters 

The following table summarizes the Control characters and commands 
available in ED: 

Control Character Function 

tc system reboot 

Te physical <cr><lf> (not actually entered in 

command) 
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ti logical tab (cols 1, 8, 15, , . . ) 

tl logical <cr>(lf> in search and substitute strings 

tx line delete 

t z string terminator 

rubout character delete 

break discontinue command (e.g., stop typing) 

Summary of ED Commands 

Command Function 



nA 


append lines 


±B 


begin bottom of buffer 


±nC 


move character positions 


±nD 


delete characters 


E 


end edit and close files (normal end) 


nF 


find string 


H 


end edit, close and reopen files 


I 


insert characters 


nJ 


place strings in juxtaposition 


±nK 


kill lines 


±nL 


move down/up lines 


nM 


macro definition 


nN 


find next occurrence with nnfnsoan 
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return to original file 


±nP 


move and print pages 


Q 


quit with no file changes 


R 


read library, file 


nS 


substitute strings 


±nT 


type lines 


±U 


translate lower to upper < 
-U 


nW 


write lines 


nZ 


sleep 


: n<cr> 


move and type ( ± nLT) 



ED Text Editing Commands 

The ED context editor contains a number of commands which enhance its 
usefulness in text editing. The improvements are found in the addition of line 
numbers, free space interrogation, and improved error reporting. 

The context editor issued with CP/M produces absolute line number prefixes 
when the "V" (Verify Line Numbers) command is issued. Following the V 
command, the line number is displayed ahead of each line in the format: 

nnnnn: 

where nnnnn is an absolute line number in the range 1 to 65535. If the 
memory buffer is empty, or if the current line is at the end of the memory 
buffer, then nnnnn appears as 5 blanks. 

The user may reference an absolute line number by preceding any command 
by a number followed by a colon, in the same format as the line number 
display. In this case, the ED program moves the current line reference to the 
absolute line number, if the line exists in the current memory buffer. Thus 
the command 

92 



345 :T 

is interpreted as **move to absolute line 345, and type the line!* Note that 
absolute line numbers are produced only during the editing process, and are 
not recorded with the file. In particular, the line numbers will change 
following a deleted or expanded section of text. 

The user may also reference an absolute line number as a backward or 
forward distance from the current line by preceding the absolute Hne number 
by a colon. Thus, the command 

:400T 

is interpreted as "type from the current line number through the Une whose 
absolute number is 400." Combining the two line reference forms, the 
command 

345::400T 

for example, is interpreted as "move to absolute line 345, then type through 
absolute line 400!' Note that absolute hne references of this sort can precede 
any of the standard ED commands. 

A special case of the V command, "OV" prints the memory buffer statistics 
in the form: 

free/ total 

where "free" is the number of free bytes in the memory buffer (in decimal), 
and "total" is the size of the memory buffer. 

ED also includes a "block move" facility implemented through the "X" 
(Xfer) command. The form 

nX 

transfers the next n lines from the current line to a temporary file called 

A. tp tptptP tptp u> * JL 1 -D 

which is active only during the editing process. In general, the user can 
reposition the current Hne reference to any portion of the source file and 
transfer hnes to the temporary file. The transferred fines accumulate one 
after another in this file, and can be retrieved by simply typing: 
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R 

which is the trivial case of the library read command. In this case, the entire 
transferred set of lines is read into the memory buffer. Note that the X 
command does not remove the transferred lines from the memory buffer, 
although a K command can be used directly after the X, and the R command 
does not empty the transferred line file. That is, given that a set of lines has 
been transferred with the X command, they can be re-read any number of 
times back into the source file. The command 

OX 

is provided, however, to empty the transferred line file. 

Note that upon normal completion of the ED program through Q or E, the 
temporary LIB file is removed. If ED is aborted through Control-C, the LIB 
file will exist if lines have been transferred, but will generally be empty (a 
subsequent ED invocation will erase the temporary file). 

Due to common typographical errors, ED requires several potentially 
disastrous commands to be typed as single letters, rather than in composite 
commands. The commands 

E (end), H (head), (original), Q (quit) 

must be typed as single letter commands. 

ED also prints error messages in the form 

BREAK "x" AT c 

where x is the error character, and c is the command where the error occurred. 
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Introduction 

The CP/M assembler reads assembly language source files from the diskette, 
and produces 8080 machine language in Intel hex format. The CP/M 
assembler is initiated by typing 

ASM filename 
or 

ASM filename.parms 

In both cases, the assembler assumes there is a file on the diskette with the 
name 

filename.ASM 

which contains an 8080 assembly language source file. The first and second 
forms shown above differ only in that the second form allows parameters to 
be passed to the assembler to control source file access and hex and print file 
destinations. 

In either case, the CP/M assembler loads, and prints the message 

CP/M ASSEMBLER VER n.n 

where n.n is the current version number. In the case of the first command, the 
assembler reads the source file with assumed file type **ASM" and creates two 
output files. 

filename.HEX 
and 

filename.PRN 

The "HEX" file contains the machine code corresponding to the original 
program in Intel hex format, and the **PRN" file contains an annotated 
listing showing generated machine code, error flags, and source lines. If errors 
occur during translation, they will be listed in the PRN file as well as at the 
console. 

The second command form can be used to redirect input and output files 
from their defaults. In this case, the "parms" portion of the command is a 
three letter group which specifies the origin of the source file, the destination 
of the hex file, and the destination of the print file. The form is 

filename.plp2p3 
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where pi, p2, and p3 are single letters 

pi: A,B, .", Y designates the disk name which contains 
the source file 

p2: A,B, ..., Y designates the disk name which will receive 
the hex file 
Z skips the generation of the hex file 

p3: A,B, "M Y designates the disk name which will receive 
the print file 
X places the listing at the console 

Z skips generation of the print file 

Thus, the command 

ASM X.AAA 

indicates that the source file (X.ASM) is to be taken from disk A, and that 
the hex (X.HEX) and the print (X.PRN) files are to be created also on disk 
A. This form of the command is implied if the assembler is run from disk A. 
That is, given that the operator is currently addressing disk A, the above 
command is equivalent to 

ASMX 

The command 

ASM X.ABX 

indicates that the source file is to be taken from disk A, the hex file is placed 
on disk B, and the listing file is to be sent to the console. The command 

ASM X.BZZ 

takes the source file from disk B, and skips the generation of the hex and print 
files. (This command is useful for fast execution of the assembler to check 
program syntax.) 

The source program format is compatible with both the Intel 8080 assembler 
(macros are not currently implemented in the CP/M assembler, however), as 
well as the Processor Technology Software Package # 1 assembler. That is, 
the CP/M assembler accepts source programs written in either format. 
There are certain extensions in the CP/M assembler which make it 
somewhat easier to use. These extensions are described below. 

98 



Program Format 

An assembly language program acceptable as input to the assembler consists 
of a sequence of statements of the form 

line* label operation operand ;comment 

where any or all of the fields may be present in a particular instance. Each 
assembly language statement is terminated with a carriage return and line 
feed (the line feed is inserted automatically by the ED program), or with the 
character "!'* which is treated as an end-of-line by the assembler (thus, 
multiple assembly language statements can be written on the same physical 
line if separated by exclamation symbols). 

The line# is an optional decimal integer value representing the source 
program line number, which is allowed on any source line to maintain 
compatibility with the Processor Technology format. In general, these line 
numbers will be inserted if a line-oriented editor is used to construct the 
original program, and thus ASM ignores this field if present. 

The label field takes the form 

identifier 
or 

identifier: 

and is optional, except where noted in particular statement types. The 
identifier is a sequence of alphanumeric characters (alphabetics and 
numbers), where the first character is alphabetic. Identifiers can be freely 
used by the programmer to label elements such as program steps and 
assembler directives, but cannot exceed 16 characters in length. All 
characters are significant in an identifier, except for the embedded dollar 
symbol ($) which can be used to improve readability of the name. Further, all 
lower case alphabetics are treated as if they were upper case. Note that the 
**:" following the identifier in a label is optional (to maintain compatibility 
between Intel and Processor Technology). Thus, the following are all valid 
instances of labels 

X X y long$name 

x : y X 1 : longer$named$data: 

X1Y2 Xlx2 x234$5678$9012$3456: 

The operation field contains either an assembler directive, or pseudo 
operation, or an 8080 machine operation code. The pseudo operations and 
machine operation codes are described below. 
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The operand field of the statement, in general, contains an expression formed 
out of constants and labels, along with arithmetic and logical operations on 
these elements. Again, the complete details of properly formed expressions 
are given below. 

The comment field contains arbitrary characters following the ";" symbol 
until the next real or logical end-of-line. These characters are read, listed, 
and otherwise ignored by the assembler. In order to maintain compatibility 
with the Processor Technology assembler, the CP/M assembler also treats 
statements which begin with a "*" in column one as comment statements, 
which are listed and ignored in the assembly process. Note that the Processor 
Technology assembler has the side effect in its operation of ignoring the 
characters after the operand field has been scanned. This causes an 
ambiguous situation when attempting to be compatible with Intel's 
language, since arbitrary expressions are allowed in this case. Hence, 
programs which use this side effect to introduce comments, must be edited 
to place a ";" before these fields in order to assemble correctly. 

The assembly language program is formulated as a sequence of statements 
of the above form, terminated optionally by an END statement. All 
statements following the END are ignored by the assembler. 

Forming the Operand 

In order to completely describe the operation codes and pseudo operations, 
it is necessary to first present the form of the operand field, since it is used in 
nearly all statements. Expressions in the operand field consist of simple 
operands (labels, constants, and reserved words), combined in properly 
formed subexpressions by arithmetic and logical operators. The expression 
computation is carried out by the assembler as the assembly proceeds. Each 
expression must produce a 16-bit value during the assembly. Further, the 
number of significant digits in the result must not exceed the intended use. 
That is, if an expression is to be used in a byte move immediate instruction, 
then the most significant 8 bits of the expression must be zero. The 
restrictions on the expression significance are given with the individual 
instructions. 



Labels 

As discussed above, a label is an identifier which occurs on a particular 
statement. In general, the label is given a value determined by the type of 
statement which it precedes. If the label occurs on a statement which 
generates machine code or reserves memory space (e.g, a MOV instruction, 
or a DS pseudo operation), then the label is given the value of the program 
address which it labels. If the label precedes an EQU or SET, then the label 
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is given the value which results from evaluating the operand field. Except for 
the SET statement, an identifier can label only one statement. 

When a label appears in the operand field, its value is substituted by the 
assembler. This value can then be combined with other operands and 
operators to form the operand field for a particular instruction. 



Numeric Constants 

A numeric constant is a 16-bit value in one of several bases. The base, called 
the radix of the constant, is denoted by a trailing radix indicator. The radix 
indicators are 

B binary constant (base 2) 

octal constant (base 8) 

Q octal constant (base 8) 

D decimal constant (base 10) 

H hexadecimal constant (base 16) 

Q is an alternate radix indicator for octal numbers since the letter is easily 
confused with the digit 0. Any numeric constant which does not terminate 
with a radix indicator is assumed to be a decimal constant. 

A constant is thus composed as a sequence of digits, followed by an optional 
radix indicator, where the digits are in the appropriate range for the radix. 
That is binary constants must be composed of and 1 digits, octal constants 
can contain digits in the range 0-7, while decimal constants contain decimal 
digits. Hexadecimal constants contain decimal digits as well as hexadecimal 
digits A (lOD), B (llD ), C (12D), D (13D), E (14D), and F (15D). Note that the 
leading digit of a hexadecimal constant must be a decimal digit in order to 
avoid confusing a hexadecimal constant with an identifier (a leading will 
always suffice). A constant composed in this manner must evaluate to a 
binary number which can be contained within a 16-bit counter, otherwise it 
is truncated on the right by the assembler. Similar to identifiers, imbedded 
"$*' are allowed within constants to improve their readability. Finally, the 
radix indicator is translated to upper case if a lower case letter is 
encountered. The following are all valid instances of numeric constants 

1234 1234D llOOB 1111$0000$1111$0000B 
1234H OFFEH 33770 33$77$22Q 
33770 0fe3h 1234d Offffh 
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Reserved Words 



There are several reserved character sequences which have predefined 
meanings in the operand field of a statement. The names of 8080 registers are 
given below, which, when encountered, produce the value shown to the right. 



A 


7 


B 





C 


1 


D 


2 


E 


3 


H 


4 


L 


5 


M 


6 


SP 


6 


PSW 


6 



(Again, lower case names have the same values as their upper case 
equivalents.) Machine instructions can also be used in the operand field, and 
evaluate to their internal codes. In the case of instructions which require 
operands, where the specific operand becomes a part of the binary bit pattern 
of the instruction (e.g, MOV A,B), the value of the instruction (in this case 
MOV) is the bit pattern of the instruction with zeroes in the optional fields 
(e.g, MOV produces 40H). 

When the symbol "$" occurs in the operand field (not imbedded within 
identifiers and numeric constants) its value becomes the address of the next 
instruction to generate, not including the instruction contained within the 
current logical line. 



String Constants 

String constants represent sequences of ASCII characters, and are 
represented by enclosing the characters within apostrophe symbols ('). All 
strings must be fully contained within the current physical line (thus 
allowing "!** symbols within strings), and must not exceed 64 characters in 
length. The apostrophe character itself can be included within a string by 
representing it asa double apostrophe (the two keystrokes "), which becomes 
a single apostrophe when read by the assembler. In most cases, the string 
length is restricted to either one or two characters (the DB pseudo operation 
is an exception), in which case the string becomes an 8 or 16 bit value, 
respectively. Two character strings become a 16-bit constant, with the 
second character as the low order byte, and the first character as the high 
order byte. 
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The value of a character is its corresponding ASCII code. There is no case 
translation within strings, and thus both upper and lower case characters 
can be represented. Note however, that only graphic (printing) ASCII 
characters are allowed within strings. Valid strings are 

W 'AB* *ab' 'c' 

»»»» »^"» »>»>»> yyjfn 

a 
'Walla Walla Wash.' 
'She said "Hello" to me.' 
'I said "Hello" to her.' 



Arithmetic and Logical Operators 

The operands described above can be combined in normal algebraic notation 
using any combination of properly formed operands, operators, and 
parenthesized expressions. The operators recognized in the operand field are 

a + b unsigned arithmetic sum of a and b 

a - b unsigned arithmetic difference between a and b 

+ b unary plus (produces b) 

- b unary minus (identical to - b) 

a * b unsigned magnitude multiplication of a and b 

a / b unsigned magnitude division of a by b 

a MOD b remainder after a / b 

NOT b logical inverse of b (all O's become I's, I's become O's), 

where b is considered a 16-bit value 
a AND b bit-by-bit logical and of a and b 

a OR b bit-by -bit logical or of a and b 

a XOR b bit-by-bit logical exclusive or of a and b 

a SHL b the value which results from shifting a to the left by 

an amount b, with zero fill 
a SHR b the value which results from shifting a to the right 

by an amount b, with zero fill 

In each case, a and b represent simple operands (labels, numeric constants, 
reserved words, and one or two character strings), or fully enclosed 
parenthesized subexpressions such as 

10 + 20 10h-f37Q LI/ 3 (L2 + 4)SHR3 

Ca'andSfh) + '0' ('B' + B) OR (PSW-hM) 

(l + (2-hc))shr(A-(B + l)) 

Note that all computations are performed at assembly time as 16-bit 
unsigned operations. Thus, -1 is computed as 0-1 which results in the value 
Offffh (i.e., all I's). The resulting expression must fit the operation code in 
which it is used. If, for example, the expression is used in a ADI (add 
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immediate) instruction, then the high order eight bits of the expression must 
be zero. As a result, the operation "ADI -1** produces an error message (-1 
becomes Offffh which cannot be represented as an 8 bit value), while **ADI 
(-1) AND OFFH" is accepted by the assembler since the "AND" operation 
zeroes the high order bits of the expression. 



Precedence of Operators 

As a convenience to the programmer, ASM assumes that operators have a 
relative precedence of application which allows the programmer to write 
expressions without nested levels of parentheses. The resulting expression 
has assumed parentheses which are defined by the relative precedence. The 
order of application of operators in unparenthesized expressions is listed 
below. Operators listed first have highest precedence (they are applied first 
in an unparenthesized expression), while operators listed last have lowest 
precedence. Operators listed on the same line have equal precedence, and are 
applied from left to right as they are encountered in an expression 

* / MOD SHL SHR 

- + 

NOT 

AND 

ORXOR 

Thus, the expressions shown to the left below are interpreted by the 
assembler as the fully parenthesized expressions shown to the right below 

a * b + c (a * b) + c 

a + b * c a + (b * c) 

a MOD b * c SHL d ((a MOD b) * c) SHL d 

a OR b AND NOT c -f d SHL e a OR (b AND (NOT (c + (d SHL e)))) 



Balanced parenthesized subexpressions can always be used to override the 
assumed parentheses, and thus the last expression above could be rewritten 
to force application of operators in a different order as 

(a OR b) AND (NOT c) + d SHL e 

resulting in the assumed parentheses 

(a OR b) AND ( (NOT c) + (d SHL e) ) 
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Note that an unparenthesized expression is well-formed only if the 
expression which results from inserting the assumed parentheses is 
well-formed. 

Assembler Directives 

Assembler directives are used to set labels to specific values during the 
assembly, perform conditional assembly, define storage areas, and specify 
starting addresses in the program. Each assembler directive is denoted by a 
"pseudo operation" which appears in the operation field of the line. The 
acceptable pseudo operations are 

ORG set the program or data origin 

End end program, optional start address 

EQU numeric "equate" 

SET numeric "set" 

IF begin conditional assembly 

ENDIF end of conditional assembly 

DB define data bytes 

DW define data words 

DS define data storage area 



The ORG Directive 

The ORG statement takes the form 

label ORG expression 

where "label" is an optional program label, and expression is a 16-bit 
expression, consisting of operands which are defined previous to the ORG 
statement. The assembler begins machine code generation at the location 
specified in the expression. There can be any number of ORG statements 
within a particular program, and there are no checks to ensure that the 
programmer is not defining overlapping memory areas. Note that most 
programs written for the CP/M system begin with an ORG statement of the 
form 

ORG lOOH 

which causes machine code generation to begin at the base of the CP/M 
transient program area. If a label is specified in the ORG statement, then the 
label is given the value of the expression (this label can then be used in the 
operand field of other statements to represent this expression). 
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The END Directive 

The END statement is optional in an assembly language program, but if it 
is present it must be the last statement (all subsequent statements are 
ignored in the assembly). The two forms of the END directive are 

label END 

label END expression 

where the label is again optional. If the first form is used, the assembly 
process stops, and the default starting address of the program is taken as 
0000. Otherwise, the expression is evaluated, and becomes the program 
starting address (this starting address is included in the last record of the 
Intel formatted machine code "hex" file which results from the assembly). 
Thus, most CP/M assembly language programs end with the statement 

END lOOH 

resulting in the default starting address of lOOH (beginning of the transient 
program area). 



The EQU Directive 

The EQU (equate) statement is used to set up synonyms for particular 
numeric values. The form is 

label EQU expression 

where the label must be present, and must not label any other statement. 
The assembler evaluates the expression, and assigns this value to the 
identifier given in the label field. The identifier is usually a name which 
describes the value in a more human-oriented manner. Further, this name is 
used throughout the program to "parameterize" certain functions. Suppose 
for example, that data received from a Teletype appears on a particular input 
port, and data is sent to the Teletype through the next output port in 
sequence. The series of equate statements could be used to define these ports 
for a particular hardware environment 

TTYBASEEQU lOH ;BASE PORT NUMBER FOR TTY 
TTYIN EQU TTYBASE ;TTY DATA IN 
TTYOUT EQU TTYBASE + 1 ;TTY DATA OUT 

At a later point in the program, the statements which access the Teletype 
could appear as 
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IN TTYIN ;READ TTY DATA TO REG - A 

OUT TTYOUT ; WRITE DATA TO TTY FROM REG-A 

making the program more readable than if the absolute I/O ports had been 
used. Further, if the hardware environment is redefined to start the Teletype 
communications ports at 7FH instead of lOH, the first statement need only 
be changed to 

TTYBASE EQU 7FH ;BASE PORT NUMBER FOR TTY 

and the program can be reassembled without changing any other 
statements. 

The SET Directive 

The SET statement is similar to the EQU, taking the form 

label SET expression 

except that the label can occur on other SET statements within the program. 
The expression is evaluated and becomes the current value associated with 
the label. Thus, the EQU statement defines a label with a single value, while 
the SET statement defines a value which is valid from the current SET 
statement to the point where the label occurs on the next SET statement. 
The use of the SET is similar to the EQU statement, but is used most often 
in controlling conditional assembly. 

The IF and ENDIF Directives 

The IF and ENDIF statements define a range of assembly language 
statements which are to be included or excluded during the assembly 
process. The form is 

IF expression 
statement #1 
statement #2 

statement #n 
ENDIF 

Upon encountering the IF statement, the assembler evaluates the 
expression following the IF (all operands in the expression must be defined 
ahead of the IF statement). If the expression evaluates to a non-zero value, 
then statement* 1 through statement* n are assembled; if the expression 
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evaluates to zero, then the statements are listed but not assembled. 
Conditional assembly is often used to write a single "generic" program which 
includes a number of possible run-time environments, with only a few 
specific portions of the program selected for any particular assembly. The 
following program segments for example, might be part of a program which 
communicates with either a Teletype or a CRT console (but not both) by 
selecting a particular value for TTY before the assembly begins 

TRUE EQU OFFFFH ; DEFINE VALUE OF TRUE 

FALSE EQU NOT TRUE ; DEFINE VALUE OF FALSE 



TTY EQU TRUE 



;TRUE IF TTY, FALSE IF CRT 



TTYBASEEQU lOH 
CRTBASEEQU 20H 
IF TTY 



;BASE OF TTY I/O PORTS 
;BASE OF CRT I/O PORTS 
;ASSEMBLE RELATIVE TO 
TTYBASE 
CONIN EQU TTYBASE ; CONSOLE INPUT 
CONOUT EQU TTYBASE + 1;C0NS0LE OUTPUT 
ENDIF 

IF NOT TTY ;ASSEMBLE RELATIVE TO 

CRTBASE 
CONIN EQU CRTBASE ;CONSOLE INPUT 
CONOUT EQU CRTBASE + 1;C0NS0LE OUTPUT 

ENDIF 

lisf CONIN ;READ CONSOLE DATA 

OUT CONOUT ;WRITE CONSOLE DATA 

In this case, the program would assemble for an environment where a 
Teletype is connected, based at port lOH. The statement defining TTY could 
be changed to 

TTY EQU FALSE 

and, in this case, the program would assemble for a CRT based at port 20H. 



The DB Directive 

The DB directive allows the programmer to define initialized storage areas in 
single precision (byte) format. The statement form is 



label DB 



e#l, e#2, .... e#n 
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where e#l through e#n are either expressions which evaluate to 8-bit values 
(the high order eight bits must be zero), or are ASCII strings of length no greater 
than 64 characters. There is no practical restriction on the number of expres- 
sions included on a single source line. The expressions are evaluated and placed 
sequentially into the machine code file following the last program address 
generated by the assembler. String characters are similarly placed into memory 
starting with the first character and ending with the last character. Strings of 
length greater than two characters cannot be used as operands in more 
complicated expressions (i.e., they must stand alone between the commas). 
Note that ASCII characters are always placed in memory with the parity bit 
reset (0). Further, recall that there is no translation from lower to upper case 
within strings. The optional label can be used to reference the data area 
throughout the remainder of the program. Examples of valid DB statements are 

data: DB 0,1,2,3,4,5 

DB data and Offh,5,377Q,l + 2 + 3 + 4 

signon: DB 'please type your name*,cr,lf,0 

DB •AB'SHR8,'C','DE'AND7FH 

The DW Directive 

The DW statement is similar to the DB statement except double precision 
(two byte) words of storage are initialized. The form is 

label DW e#l,e#2, ..., e#n 

where e#l through e#n are expressions which evaluate to 16-bit results. 
Note that ASCII strings of length one or two characters are allowed, but 
strings longer than two characters disallowed. In all cases, the data storage 
is consistent with the 8080 processor: the least significant byte of the 
expression is stored first in memory, followed by the most significant byte. 
Examples are 

doub: DW Offefh,doub + 4,signon-$,255 + 255 
DW 'a', 5, 'ab', 'CD', 6 shl 8 or lib 

The DS Directive 

The DS statement is used to reserve an area of uninitialized memory, and 
takes the form 

label DS expression 

where the label is optional. The assembler begins subsequent code 
generation after the area reserved by the DS. Thus, the DS statement given 
above has exactly the same effect as the statement 
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label: EQU $ ; LABEL VALUE IS CURRENT CODE LOCATION 
ORG $ + expression ;MOVE PAST RESERVED AREA 

Operation Codes 

Assembly language operation codes form the principal part of assembly 
language programs, and form the operation field of the instruction. In 
general, ASM accepts all the standard mnemonics for the Intel 8080 
microcomputer, which are given in detail in the Intel manual 8080 Assembly 
Language Programming Manual Labels are optional on each input line 
and, if included, take the value of the instruction address immediately before 
the instruction is issued. The individual operators are listed briefly in the 
following sections for completeness, although it is understood that the Intel 
manuals should be referenced for exact operator details. In each case, 

e3 represents a 3-bit value in the range of 0-7 which can be 

one of the predefined registers A, B, C, D, E, H, L, M, SP, 
or PSW. 

e8 represents an 8-bit value in the range 0-255 

el6 represents a 16-bit value in the range 0-65535 

which can themselves be formed from an arbitrary combination of operands 
and operators. In some cases, the operands are restricted to particular values 
within the allowable range, such as the PUSH instruction. These cases will 
be noted as they are encountered. 

In the sections which follow, each operation code is listed in its most general 
form, along with a specific example, with a short explanation and special 
restrictions. 



Jumps, Calls and Returns 

The Jump, Call and Return instructions allow several different forms which 
test the condition flags set in the 8080 microcomputer CPU. The forms are 



Jump unconditionally to label 
Jump on non zero condition to label 
Jump on zero condition to label 
Jump no carry to label 
Jump on carry to label 
Jump on parity odd to label 
Jump on even parity to label 
Jump on positive result to label 
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JMB 


el6 


JMP 


LI 


JNZ 


el6 


JMP 


L2 


JZ 


el6 


JMP 


lOOH 


JNC 


el6 


JNC 


Ll+4 


JC 


el6 


JC 


L3 


JPO 


el6 


JPO 


$ + 8 


JPE 


el6 


JPE 


L4 


JP 


el6 


JP 


GAMMA 



JM el6 
CALL el6 
CNZ el6 



CZ 

CNC 

CC 

CPO 

CPE 

CP 

CM 

RST 



RET 

RNZ 

RZ 

RNC 

RC 

RPO 

RPE 

RP 

RM 



el6 
el6 
el6 
el6 
el6 
el6 
el6 

e3 



JM al 

CALL SI 

CNZ S2 

CZ 

CNC 

CC 

CPO 

CPE 

CP 

CM 



lOOH 

Si +4 

S3 

$+8 

S4 

GAMMA 

bl$c2 



RST 



Jump on minus 
Call subroutine 
Call subroutine 
Call subroutine 
Call subroutine 
Call subroutine 
Call subroutine 
Call subroutine 
Call subroutine 
Call subroutine 



to label 

unconditionally 
if non zero flag 
on zero flag 
if no carry set 
if carry set 
if parity odd 
if parity even 
if positive result 
if minus flag 



Programmed "restartl' equivalent to 
CALL 8*e3, except one byte call 

Return from subroutine 
Return if non zero flag set 
Return if zero flag set 
Return if no carry 
Return if carry flag set 
Return if parity is odd 
Return if parity is even 
Return if positive result 
Return if minus flag is set 



Immediate Operand Instructions 

Several instructions are available which load single or double precision 
registers, or single precision memory cells, with constant values, along with 
instructions which perform immediate arithmetic or logical operations on 
the accumulator (register A). 



MVI e3,e8 


MVI 


B,255 


ADIeS 


ADI 


1 


ACI e8 


ACI 


OFFH 


SUIe8 


SUI 


L + 3 


SBIeS 

ANIeS 


SBI 

ANI 


LANDllB 
$ AND 7FH 


XRIe8 


XRI 


1111$0000B 


ORI e8 


ORI 


LAND 1 + 1 



Move immediate data to register A, 
B, C, D, E, H, L, or M (memory) 
Add immediate operand to A with- 
out carry 

Add immediate operand to A with 
carry 

Subtract from A without borrow 
(carry) 

Subtract from A with borrow (carry) 
Logical "and" A with immediate 
data 

"Exclusive or" A with immediate 
data 
Logical "or" A with immediate data 



HI 



CPIeS 



CPI 'a' 



LXIe3,el6 LXI B,100H 



Compare A with immediate data 
(same as SUI except register A not 
changed) 

Load extended immediate to register 
pair (e3 must be equivalent to 
B,D,H, or SP) 



Increment and Decrement Instructions 

Instructions are provided in the 8080 repertoire for incrementing or 
decrementing single and double precision registers. The instructions are 



Single precision increment register 

(e3 produces one of A, B, C, D, E, H, 

L.M) 

Single precision decrement register 

{e3 produces one of A, B, C, D, E, H, 

L,M) 

Double precision increment register 

pair (e3 must be equivalent to 

B,D.H,orSP) 

Double precision decrement register 

pair (e3 must be equivalent to 

B,D,H, or SP) 



INRe3 


INR E 


DCRe3 


DCR A 


INXe3 


INX SP 


DCXeS 


DCX B 



Data Movement Instructions 



Instructions which move data from memory to the CPU and from CPU to 
memory are given below 



MOV e3,e3 

LDAX e3 
STAX e3 
LHLD el6 
SHLD el6 



MOV A,B 

LDAXB 
STAX D 
LHLD LI 
SHLD L5 + X 



Move data to leftmost element 

from rightmost element (e3 

produces one of A, B, C, D, E, H^ 

L, or M). MOV M,M is disallowed 

Load register A from computed 

address (e3 must produce either B 

orD) 

Store register A to computed 

address (e3 must produce either B 

orD) 

Load HL direct from location el6 

(double precision load to H and 

L) 

Store HL direct to location el6 

(double precision store from H 

and L to memory) 
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LDA el6 
STA el6 


LDA Gamma 
STA X3-5 


POP e3 


POP PSW 


PUSH e3 


PUSHB 


IN e8 


IN 


OUT e8 


OUT 255 


XTHL 




PCHL 




SPHL 




XCHG 





Load register A from address el6 

Store register A into memory at 

el6 

Load register pair from stack, set 

SP (e3 must produce one of B, D, 

H, or PSW) 

Store register pair into stack, set 

SP (e3 must produce one of B, D, 

H, or PSW) 

Load register A with data from 

port e8 

Send data from register A to port 

e8 

Exchange data from top of stack 

with HL 

Fill program counter with data 

from HL 

Fill stack pointer with data from 

HL 

Exchange DE pair with HL pair 



Arithmetic Logic Unit Operations 

Instructions which act upon the single precision accumulator to perform 
arithmetic and logic operations are 



ADD eS 


ADD B 


ADC eS 


ADC L 


SUB eS 


SUB H 


SEE e3 


SEE 2 


ANA e3 


ANA 1 + 1 


XRA e3 


XRA A 


ORA e3 


ORA B 


CMP e3 


CMP H 


DAA 





CMA 



Add register given by e3 to ac- 
cumulator without carry (e3 
must produce one of A, B, C, D, E, 
H,orL) 

Add register to A with carry, e3 as 
above 

Subtract reg e3 from A without 
carry, e3 is defined as above 
Subtract register e3 from A with 
carry, e3 defined as above 
Logical "and" reg with A, e3 as 
above 

"Exclusive or'* with A, e3 as above 
Logical "or" with A, e3 defined as 
above 

Compare register with A, e3 as 
above 

Decimal adjust register A based 
upon last arithmetic logic unit 
operation 
Complement the bits in register A 
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STC 

CMC 

RLC 



RRC 

HAL 
RAR 

DAD e3 



DADB 



Set the carry flag to 1 
Complement the carry flag 
Rotate bits left, {re)set carry as a 
side effect (high order A bit 
becomes carry) 

Rotate bits right, (re)set carry as 
side effect (low order A bit 
becomes carry) 

Rotate carry /A register to left 
(carry is involved in the rotate) 
Rotate carry/A register to right 
(carry is involved in the rotate) 

Double precision add register 
pair e3 to HL (e3 must produce B, 
D, H, or SP) 



Control Instructions 

The four remaining instructions are categorized as control instructions, and 
are listed below 



HLT 
DI 
EI 
NOP 



Halt the 8080 processor 
Disable the interrupt system 
Enable the interrupt system 
No operation 



Error Messages 



When errors occur within the assembly language program, they are listed as 
single character flags in the leftmost position of the source listing. The line 
in error is also echoed at the console so that the source listing need not be 
examined to determine if errors are present. The error codes are 



E 



Data error: element in data statement cannot be 
placed in the specified data area 

Expression error: expression is ill-formed and 
cannot be computed at assembly time 



N 



Label error: label cannot appear in this context 
(may be duplicate label) 

Not implemented: features which will appear in 
future ASM versions (e.g., macros) are recognized, 
but flagged in this version 
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Overflow: expression is too complicated (i.e., too 
many pending operators) to compute; simplify it 

Phase error: label does not have the same value on 
two subsequent passes through the program 



R Register error: the value specified as a register is not 

compatible with the operation code 

V Value error: operand encountered in expression is 

improperly formed 

Several error messages are printed which are due to terminal error conditions 



NO SOURCE FILE 
PRESENT 



The file specified in the ASM command does 
not exist on disk 



NO DIRECTORY SPACE The disk directory is full; erase files which are 

not needed, and retry 



SOURCE FILE NAME 
ERROR 



Improperly formed ASM file name (e.g., it is 
specified with "?" fields) 



SOURCE FILE READ 
ERROR 



Source file cannot be read properly by the 
assembler, execute a TYPE to determine the 
point of error 



OUTPUT FILE WRITE 
ERROR 

CANNOT CLOSE FILE 



Output files cannot be written properly, most 
likely cause is a full disk; erase and retry 

Output file cannot be closed, check to see if 
disk is write protected 
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A Sample Session 

The following session shows interaction with the assembler and debugger in the 
development of a simple assembly language program. 

ASn SORT Assemble SORT. ASM 

CP/N ASSEtlBLER - VER 1 8 

^ 1 5C next free address 

ee3H USE FACTOR % of table used 00 to FF (hexadecimal) 

END OF ASSEHBLV 

DIR SORT * 

SORT ASH source file 

SORT BAK backup from last edit 

SORT P R N print file (contains lab characters) 

SORT HEX machine code file 

A>TYPE SORT PRN 

Source line 

machine code location ' SORT PftOCRAH IH CP/h ASSEhBLY LAHCUACE 

. , START AT THE 8EC1HN1NC OF THE TRAHSIENT PROGRAR UU 

eiee^ — ^ org leeH 

generated machine code 

eiee '2Meei^«-^ sort lxi h. su , address switch toggle 

ei03 3661 MVI Y\, \ .SET TO 1 FOP FIRST ITERATION 

9185 214781 L;<t H. 1 .ADDRESS INDEX 

8186 3680 nvi K. 8 . I > 8 

COMPARE I UITn ARRAY SIZE 

ei8A 7E COHP: nOV A.n .A REGISTER » I 

ei8B FE89 CPl N-l .CY SET IF I < (N-t) 

618D D219ei JHC CONT .CONTINUE IF 1 <« (H-2) 

END OF ONE PASS THROUGH DATA 
etl8 214681 LXI H. SU .CHECK FOR ZERO SWITCHES 

8113 7E67C28881 NOV A> HI ORA A< JN2 SORT .Et^D OF SORT IF SU«e 

0116 FF RST 7 .CO TO THE DEBUGGER INSTEAD OF REt 

/ toincated 



/: 



CONTINUE THIS PhSS 

ADDRESSIHG I. SO LOAD AVCI) INTO REGISTERS 
8119 5F16882148C0NT; HOV E/A« HVI D.8« LXI H.AV DAD Dl DAD D 
8121 4E792346 NOV C.d! nOV A. C • INX H< HOV BH 

LOU ORDER BYTE IN A AND C. HIGH ORDER BYTE IH 6 



HOV H AND L TO hDDRESS AV(1*1> 

8125 23 IHX H 

i 

CONPARE VALUE WITH REGS CONTAINING AV(t> 

8126 965776239E SUB N> NOV D.A> NOV A. B ! INX H' SGB fl .SUBTRACT 

BORROU SET IF AVCIM) > AV< I ) 
812B DA3F81 JC INCI .SKIP IF IN PROPER ORDER 

CHECK FOk EQUAL VALUES 
8I2E 62CA3F6I ORA D' JZ IHfl .SKIP IF AVM ) « AV(I*t> 

8132 56782B5E MOV D.N! NOV N.B! DCX H* NOV E.H 

8136 712B722B73 NOV N.C! DCX HI NOV M. • DCX H' MOV N. E 

i INCREMENT SWITCH COUHT 

ei3B 21460134 LXI H.SU! INR M 
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013F 2J47ei34C3INCI. 



8146 66 SU; 

6147 I 

6t48 6S6e64661EAV 
e66A • N 

6 1 5 C ^^ — equate value 
A>TYPE SORT HEX 



IHCRCHENT I 

LXI H. I ! INR n\ jnP COHP 

DATA DEFIMITIOM SECTION 



DB 
DS 
DU 

EQU 
END 



6 .RESERVE SPACE FOR SUITCH COUNT 
t ;SPACE FOR INDEX 
5. 186, 36. 56, i:e. 7. IB ei 8. 19 6. 196, -3276? 
<»-ftV)/2 ,COnPUTE N INSTEAD OF PRE 



1 66 1 66662 1466 1 366 121 476 1 3 6687EFE89D2 1961 46 
. 1 66 1 1 66621 466 17EB7C26d81FF5F 16662 14 881 1983 
: I6612 666194E7 92 3 4623 965 778239£DA3FeiB2CAA7 
. 16813666 3F61567e2B5E7l2B7 22B73214 66134 21C7 
: 67dl466d476134C38A61666E 

1 66 14 6 6665 6 66 466 1 E 66 3 266 1 4 66 67 60E 88 3 2C 6 IBB 

64615666646661866E 
. 6666666668 
A>DDT SORT HEX start debug run 

16X DDT VER 1 6 

NEXT PC 

6 1 5C 68 68 default address (no address on EfSD statement) 

-XP 

P-0666 188 changePCto 100 



machine code 
in HEX format 



-UFFFF untrace for 63535 steps 










abort with 


















/rubout 
H, 6146 '6186 


C62dH8E6]6 


A«86 


6^6686 


D»0668 


H-666e 


S=8166 


p»eie6 


LXl 


-Tt8 trace 10,^ steps 














C6Z6H6E616 


A«81 


B-6886 


0-8866 


H-8146 


8-6166 


P-6166 


LXI 


H,6146 


C62dn8E616 


A«8l 


8-8666 


D-6666 


H-6146 


S-6188 


P-6163 


HVl 


N. 61 


C6Z6I18E616 


A«81 


B-8866 


D-8868 


H-8146 


S-6166 


P«ei65 


LXl 


H, 8147 


C6Z6nBE6I6 


A-81 


B-6666 


D-B668 


N-ei4r 


S.8166 


P»6t6d 


nvi 


N, 66 


C828n6E8I6 


A-81 


B-8686 


D«8d68 


H-6147 


S»61d6 


P»616A 


NOV 


A« H 


C6Z6n6E616 


A»66 


8»6668 


D-d668 


H=8147 


S«6166 


P^tdlBB 


CPI 


69 


C1Z8K1E816 


A = 66 


B»8688 


D-8d68 


H=6I47 


S-6166 


P«ei6D 


JNC 


8U9 


C1Z6N1E6I6 


A»66 


8-6606 


D-8666 


H*8M7 


S=6166 


P--8116 


LXI 


H. 6146 


ClZ6niE6I6 


A-68 


8-6666 


D-8666 


H-6146 


S-6166 


P«8ll3 


nov 


A, n 


C1Z8H1E616 


A-81 


8-8688 


D-6668 


H-6146 


S-6166 


P-6 11 4 


ORA 


A 


C6Z8rt8E618 


A-81 


B-6666 


D-6668 


H-6146 


S-6166 


P-B115 


JNZ 


6166 


C6Z8t16Edl6 


A-81 


6-6666 


D-8868 


H-6146 


S-6166 


P-8166 


LXI 


H, 8146 


C8Z6H6E6I6 


A-61 


B-6688 


D-6666 


H-6t46 


S-6166 


P-6163 


NVI 


n» 61 


C6Z8n8E616 


A881 


B-8668 


D-6668 


H-6146 


3»6166 


P-8165 


LXI 


H, 8 147 


C626N8E616 


A«61 


B-6688 


D-8668 


H-614? 


S-6166 


P-6168 


nvi 


n, 66 


C6Z6neE616 


A-61 


B-0 68 6 


D-68d8 


H«e.l47 


S>6166 


P-eiBA 


NOV 


A, n*81 68 


-AieD 
















* 


1 ?ft *^^ * * ^ change to a jump on carry 






slopped at -^ 
lOBH 


-XP 



















P-616B 106 reset program counter back to beginning of program 
- T 1 6 trace execution for I OH steps 



C626H0E6I6 A-66 B-B688 D-6d6d H-6147 

C6Z6N8Edl6 A-86 B-8668 D-6668 H-6146 

C6ZdH8E6I6 A-66 8-6686 

C6Z6I18E6I6 A-86 8-8686 

C6Z6n8Eei6 A-66 B<8886 

C6Z8nBE6I8 A-86 8-8666 

C1Z6H1E6I6 A-66 B-8686 



H-6146 
H»6147 

H-6147 
H-6147 



$-6166 P-dl66 
S-6168 P-6163 
S-6166 P-8165 
S-6166 Pa8168 
$-6186 P-dl6A 
S-8166 P-6168 



LXI 
NVI 
LXl 
NVI 
NOV 
CPI 



D-B666 

D-6668 

D-8e68 

D-6666 

D»868e H-6147 S-6166 P-618D JC 
C1Z6H1E6I6 A-86 B-8686 D-8668 H-6147 S-6166 P-6119 HOV 
ClZeNlE616 A-66 6>8686 D-8668 H-6147 S-6166 P-611A NVI 
C126NIE6I6 A-86 B-6666 D-8808 H-6147 S-6166 P-61IC LXl 
ClZ6niE616 A-86 B-6688 D-6866 H-814B $-6166 P.611F DAD 
(?6Z8Hl£6I6 A-66 8-6660 D»6668 H«6148 S-6166 P-6126 DAD 



H.6146 

N.61 

H,6147 

N>6 

A.N 

89 

6119 

E.A 

D.60 

N,0148 

D 





altered instnjction 
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kez^HiEeie 


A^ed B= 


=6660 D»6660 H:=6148 


$=6166 


P=6l^l HOV 


C. 11 


cezoHiEeie 


A»8d B' 


= 6685 D»66dd H»dl48 


S=6166 


P = ^l2:2 ilOV 


(k.C 


cezBHiEdie 


A»65 B- 


=8683 D»8e68 H«6148 


$36168 


P»dl23 IHX 


H 


cezenieeie 


A>85 B> 


.6685 D-866d H-6149 


S-6166 


p«di24 nov 


e^n«8i29 


-Liee 
eiee 

8163 


LXl 

HVl 


H,6146 
H.81 


. 




Automatic 
breakpoint 


^ 


8165 


LXl 


H,6147 


i 








8168 
616A 
8166 


nvi 

nov 

CPl 


N.66 

A.n 

69 


1 list some code 
V from lOOH 








816D 


JC 


6119 


/ 








6116 


LXI 


H.8146 


1 








8113 


HOV 


A.n 


1 








81 14 


ORft 


A 


j 








61 15 

-u 


JNZ 


dt68 


^ 








8118 
8119 


RST 
HOV 


87 
E.A 


/ list more 








81 lA 


nvi 


D.86 


( 








6I1C 


LXl 


H.8148 


) 









' abort list with ruboul 

- C * 1 18 start program from current PC {01 25H) and mn in real time to 1 1 BH 

• 6 1 2 7 stopped with an external interrupt 7 from front panel (program was looping indefinitely) 
' T 4 look at looping program in trade mode . 

CdZ6l18E616 A-3e B-8664 D-8666 H-6196 S-6188 P-6127 HOV B.A 

C6Z6n8E6I6 A«3e B-6664 D-3866 H-6156 S-6166 P-6128 HOV A. 8 

C6Z6HdE6I6 A»6d B>8664 D-3866 H-6156 S-6166 P«6129 INX H 

C6ZeH8E616 A^Bd B-6664 D-3866 H-dlS7 $-6166 P-612A SBB n«612B 



-D148 



data is sorted, but program doesn t stop 



8148 85 60 67 68 14 86 IE 66 

8156 32 66 64 68 64 86 2C 61 E8 63 81 86 66 68 66 66 2 D D 
8166 66 86 66 68 66 88 86 66 68 vu 86 66 66 66 66 66 

- GO return to CP/M 

DOT SORT. HEX reload the memory image 

16K DDT VER 1.6 
HEXT PC 
615C 6666 
-XP 

P-6666 166 Set PC to beginning of program 

* L 1 6 D 

list bad opcode 

816D JHC 6119^ 
6118 LXl H.6146 

" abort list with nibout 

- A 1 6 D assemble new opcode 
616D JC 119 

6116 

- L 1 6 6 list starting section of program 



6168 


LXI 


H.8146 


8163 


HVl 


H.61 


8165 


LXl 


H.8147 


6168 


HVl 


H.66 



~ abort list with rubout 

- A 1 6 3 change "switch" initialization to 00 
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eid3 MVi n.e 
dies 

- " C return to CP/M with ctl-c (GO works as well) 

SftVE 1 SORT, con save 1 page (256 bytes, from lOOH to I FFMH) on disk in case 

we have to reload later 
A>DDT SORT, con restart DDT with "r. 

saved memory image 
UK LDT VER 1 
MEXT PC 

eiree e l ee -com" nie always starts with address lOOH 
' G run the program from PC = I OOH 

• 8118 programmed stop (RST 7) encountered 
^D140 

^ data properly sorted 

8148 89 88 87 88 H 88 IE 88 

8158 32 88 64 88 €4 88 2C 81 E8 83 81 88 88 88 88 88 2 D 

81(>8 88 88 88 88 88 88 88 88 88 08 88 88 88 88 88 88 

8178 88 88 88 d8 88 88 88 88 88 08 88 88 88 88 88 88 

- GOretumtoCP/M 

ED SORTASn make changes to ohginal program 

• N. ergeTT find next -.O" 

^^ HVI n.B ,1 « 8 

• - up one line in text 

LXl H. I .ADDRESS INDEX 

• - up another line 

MVl M,l .SET TO 1 FOR FIRST ITERATION 

• K T kill line and type next line 

LX] H, I .ADDRESS INDEX 

• I insert new line 

MVl n,8 *2ER0 SU 

• T 

^^ LXl H. 1 .ADDRESS INDEX 

• NJNC^8T 

JNC*T 

GOUT ^CONTINUE IF I <> <H-2> 

•-2D1C<3)&LT 

JC CONT >CONTINUE IF I <= <H-2> 

• E source from disk A 

/^ hex to disk A 
ASM SORT AA 2^*^ skip pm file 

CP/H ASSEMBLER - VER 1 

8 J 5 C next address to assemble 
883H USE FACTOR 
END OF ASSEMBLY 

DDT SORT NEX test program changes 

UK DDT VER 1 8 

NEXT PC 
OliC 6Ci88 
-G1&8 

• 8118 

data sorted 



8148 85 88 87 88 14 88 IE 88 

8158 32 88 64 88 64 88 2C 81 E8 83 81 88 88 08 88 88 2 D 
8168 8 8 8 8 8 88 08 8 8 8 8 8 8 86 88 U8 8 8 Otf 8»J hu 

- abort with rutx)ut 

-CO retum to CP/M — program checks OK. 
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Introduction 

The DDT program allows dynamic interactive testing and debugging of 
programs generated in the CP/M environment. The debugger is initiated by 
typing one of the following commands at the CP/M Console Command level 

DDT 

DDT filename.HEX 

DDT filename.COM 

where "filename" is the name of the program to be loaded and tested. In both 
cases, the DDT program is brought into main memory in the place of the 
Console Command Processor (refer to the CP/M Interface Guide for 
standard memory organization), and thus resides directly below the Basic 
Disk Operating System portion of CP/M. The BDOS starting address, which 
is located in the address field of the JMP instruction at location 5H, is altered 
to reflect the reduced Transient Program Area size. 

The second and third forms of the DDT command shown above perform the 
same actions as the first, except there is a subsequent automatic load of the 
specified HEX or COM file. The action is identical to the sequence of 
commands 

DDT 

Ifilename.HEX or Ifilename.COM 
R 

where the I and R commands set up and read the specified program to test. 
(See the explanation of the I and R commands below for exact details.) 

Upon initiation, DDT prints a sign-on message in the format 

nnK DDT-s VER m.m 

where nn is the memory size (which must match the CP/M system being 
used), s is the hardware system which is assumed, corresponding to the codes 

D Digital Research standard version 

M MDS version 

I IMSAI standard version 

O Omron systems 

S Digital Systems standard version 

and m.m is the revision number. 
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Following the sign on message, DDT prompts the operator with the 
character **-" and waits for input commands from the console. The operator 
can type any of several single character commands, terminated by a carriage 
return to execute the command. Each hne of input can be line-edited using 
the standard CP/M controls 

rubout remove the last character typed 

Control-X remove the entire line, ready for re-typing 
Control-C system reboot 

Any command can be up to 32 characters in length (an automatic carriage 
return is inserted as the 33rd character), where the first character determines 
the command type 

A enter assembly language mnemonics with operands 

D display memory in hexadecimal and ASCII 

F fill memory with constant data 

G begin execution with optional breakpoints 

I set up a standard input file control block 

L list memory using assembler mnemonics 

M move a memory segment from source to destination 

R read program for subsequent testing 

S substitute memory values 

T trace program execution 

U untraced program monitoring 

X examine and optionally alter the CPU state 

The command character, in some cases, is followed by zero, one, two, or three 
hexadecimal values which are separated by commas or single blank 
characters. All DDT numeric output is in hexadecimal form. In all cases, the 
commands are not executed until the carriage return is typed at the end of 
the command. 

At any point in the debug run, the operator can stop execution of DDT using 
either a Control-C or GO (jmp to location OOOOH), and save the current 
memory image using a SAVE command of the form 
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SAVE n filename.COM 

where n is the number of pages (256 byte blocks) to be saved on disk. The 
number of blocks can be determined by taking the high order byte of the top 
load address and converting this number to decimal. For example, if the 
highest address in the Transient Program Area is 1234H then the number of 
pages is 12H, or 18 in decimal. Thus the operator could type a Control-C 
during the debug run, returning to the Console Processor level, followed by 

SAVE 18 X.COM 

The memory image is saved as X.COM on the diskette, and can be directly 
executed by simply typing the name X. If further testing is required, the 
memory image can be recalled by typing 

DDT X.COM 

which reloads the previously saved program from location lOOH through 
page 18 (12FFH). The machine state is not a part of the COM file, and thus 
the program must be restarted from the beginning in order to properly test 
it. 

DDT Commands 

The individual commands are given below in some detail. In each case, the 
operator must wait for the prompt character (-) before entering the 
command. If control is passed to a program under test, and the program has 
not reached a breakpoint, control can be returned to DDT by executing a 
RST 7 from the front panel (note that the rubout key should be used instead 
if the program is executing a T or U command). In the explanation of each 
command, the command letter is shown in some cases with numbers 
separated by commas, where the numbers are represented by lower case 
letters. These numbers are always assumed to be in a hexadecimal radix, and 
from one to four digits in length (longer numbers will be automatically 
truncated on the right). 

Many of the commands operate upon a **CPU state'* which corresponds to 
the program under test. The CPU state holds the registers of the program 
being debugged, and initially contains zeroes for all registers and flags except 
for the program counter (P) and stack pointer (S), which default to lOOH. 
The program counter is subsequently set to the starting address given in the 
last record of a HEX file if a file of this form is loaded (see the I and R 
commands). 



125 



The A (Assemble) Command 

DDT allows inline assembly language to be inserted into the current 
memory image using the A command which takes the form 

As 

where s is the hexadecimal starting address for the inline assembly. DDT 
prompts the console with the address of the next instruction to fill, and reads 
the console, looking for assembly language mnemonics (see the Intel 8080 
Assembly Language Reference Card for a Hst of mnemonics), followed by 
register references and operands in absolute hexadecimal form. Each 
successive load address is printed before reading the console. The A 
command terminates when the first empty line is input from the console. 

Upon completion of assembly language input, the operator can review the 
memory segment using the DDT disassembler. (See the L command.) 

Note that the assembler/disassembler portion of DDT can be overlayed by 
the transient program being tested, in which case the DDT program 
responds with an error condition when the A and L commands are used. 

The D (Display) Command 

The D command allows the operator to view the contents of memory in 
hexadecimal and ASCII formats. The forms are 

D 

Ds 

Ds,f 

In the first case, memory is displayed from the current display address 
(initially lOOH), and continues for 16 display lines. Each display line takes 
the form shown below 

aaaa bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb cccccccccccccccc 

where aaaa is the display address in hexadecimal, and bb represents data 
present in memory starting at aaaa. The ASCII characters starting at aaaa 
are given to the right (represented by the sequence of c's), where non-graphic 
characters are printed as a period (. ) symbol. Note that both upper and lower 
case alphabetics are displayed, and thus will appear as upper case symbols on 
a console device that supports only upper case. Each display line gives the 
values of 16 bytes of data, except that the first hne displayed is truncated so 
that the next line begins at an address which is the multiple of 16. 
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The second form of the D command shown above is similar to the first, except 
that the display address is first set to address s. The third form causes the 
display to continue from address s through address f. In all cases, the display 
address is set to the first address not displayed in this command, so that a 
continuing display can be accomplished by issuing successive D commands 
with no explicit addresses. 

Excessively long displays can be aborted by pushing the rubout key. 

The F (Fill) Command 

The F command takes the form 

Fs,f,c 

where s is the starting address, f is the final address, and c is a hexadecimal 
byte constant. The effect is as follows: DDT stores the constant c at address 
s, increments the value of s and tests against f. If s exceeds f then the 
operation terminates, otherwise the operation is repeated. Thus, the fill 
command can be used to set a memory block to a specific constant value. 

The G (Go) Command 

Program execution is started using the G command, with up to two optional 
breakpoint addresses. The G command takes one of the forms 

G 

Gs 

Gs,b 

Gs,b,c 

G,b 

G,b,c 

The first form starts execution of the program under test at the current value 
of the program counter in the current machine state, with no breakpoints set 
(the only way to regain control in DDT is through a RST 7 execution). The 
current program counter can be viewed by typing an X or XP command. The 
second form is similar to the first except that the program counter in the 
current machine state is set to address s before execution begins. The third 
form is the same as the second, except that program execution stops when 
address b is encountered (b must be in the area of the program under test). 
The instruction at location b is not executed when the breakpoint is 
encountered. The fourth form is identical to the third, except that two 
breakpoints are specified, one at b and the other at c. Encountering either 
breakpoint causes execution to stop, and both breakpoints are subsequently 
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cleared. The last two forms take the program counter from the current 
machine state, and set one and two breakpoints, respectively. 

Execution continues from the starting address in real-time to the next 
breakpoint. That is, there is no intervention between the starting address 
and the break address by DDT. Thus, if the program under test does not 
reach a breakpoint, control cannot return to DDT without executing a RST 
7 instruction. Upon encountering a breakpoint, DDT stops execution and 
types 



where d is the stop address. The machine state can be examined at this point 
using the X (Examine) command. The operator must specify breakpoints 
which differ from the program counter address at the beginning of the G 
command. Thus, if the current program counter is 1234H, then the 
commands 

G,1234 
and 

0400,400 

both produce an immediate breakpoint, without executing any instructions 
whatsoever. 



The I (Input) Command 



The I command allows the operator to insert a file name into the default file 
control block at 5CH (the file control block created by CP/M for transient 
programs is placed at this location; see the CP/M Interface Guide). The 
default FCB can be used by the program under test as if it had been passed 
by the CP/M Console Processor. Note that this file name is also used by DDT 
for reading additional HEX and COM files. The form of the I command is 

Ifilename 
or 

Ifilename.fi letype 

If the second form is used, and the filetype is either HEX or COM, then 
subsequent R commands can be used to read the pure binary or hex format 
machine code (see the R command for further details). 
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The L (List) Command 

The L command is used to list assembly language mnemonics in a particular 
program region. The forms are 

L 

Ls 

Ls,f 

The first command lists twelve lines of disassembled machine code from the 
current list address. The second form sets the list address to s, and then lists 
twelve lines of code. The last form lists disassembled code from s through 
address f. In all three cases, the list address is set to the next unlisted location 
in preparation for a subsequent L command. Upon encountering an 
execution breakpoint, the list address is set to the current value of the 
program counter (see the G and T commands). Again, long typeouts can be 
aborted using the rubout key during the list process. 

The M (Move) Command 

The M command allows block movement of program or data areas from one 
location to another in memory. The form is 

Ms,f,d 

where s is the start address of the move, f is the final address of the move, and 
d is the destination address. Data is first moved from s to d, and both 
addresses are incremented. If s exceeds f then the move operation stops, 
otherwise the move operation is repeated. 

The R (Read) Command 

The R command is used in conjunction with the I command to read COM 
and HEX files from the diskette into the transient program area in 
preparation for the debut run. The forms are 

R 
Rb 

where b is an optional bias address which is added to each program or data 
address as it is loaded. The load operation must not overwrite any of the 
system parameters from OOOH through OFFH (i.e., the first page of memory ). 
If b is omitted, then b = 0000 is assumed. The R command requires a previous 
I command, specifying the name of a HEX or COM file. The load address for 
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each record is obtained from each individual HEX record, while an assumed 
load address of lOOH is taken for COM files. Note that any number of R 
commands can be issued following the I command to re-read the program 
under test, assuming the tested program does not destroy the default area at 
5CH. Further, any file specified with the filetype *'COM" is assumed to 
contain machine code in pure binary form (created with the LOAD or SAVE 
command), and all others are assumed to contain machine code in Intel hex 
format (produced, for example, with the ASM command). 

Recall that the command 

DDT filename.filetype 

which initiates the DDT program is equivalent to the commands 

DDT 

-Ifilename.filetype 

-R 

Whenever the R command is issued, DDT responds with either the error 
indicator "?" (file cannot be opened, or a checksum error occurred in a HEX 
file), or with a load message taking the form 

NEXT PC 
nnnn pppp 

where nnnn is the next address following the loaded program, and pppp is the 
assumed program counter (lOOH for COM files, or taken from the last record 
if a HEX file is specified). 

The S (Set) Command 

The S command allows memory locations to be examined and optionally 
altered. The form of the command is 

Ss 

where s is the hexadecimal starting address for examination and alteration 
of memory. DDT responds with a numeric prompt, giving the memory 
location, along with the data currently held in the memory location. If the 
operator types a carriage return, then the data is not altered. If a byte value 
is typed, then the value is stored at the prompted address. In either case, 
DDT continues to prompt with successive addresses and values until either 
a period (.) is typed by the operator, or an invalid input value is detected. 
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The T (Trace) Command 

The T command allows selective tracing of program execution for 1 to 65535 
program steps. The forms are 

T 
Tn 

In the first case, the CPU state is displayed, and the next program step is 
executed. The program terminates immediately, with the termination 
address displayed as 

*hhhh 

where hhhh is the next address to execute. The display address (used in the 
D command) is set to the value of H and L, and the list address (used in the 
L command) is set to hhhh. The CPU state at program termination can then 
be examined using the X command. 

The second form of the T command is similar to the first, except that 
execution is traced for n steps (n is a hexadecimal value) before a program 
breakpoint occurs. A breakpoint can be forced in the trace mode by typing 
a rubout character. The CPU state is displayed before each program step is 
taken in trace mode. The format of the display is the same as described in the 
X command. 

Note that program tracing is discontinued at the interface to CP/M, and 
resumes after return from CP/M to the program under test. Thus, CP/M 
functions which access I/O devices, such as the diskette drive, run in 
real-time, avoiding I/O timing problems. Programs running in trace mode 
execute approximately 500 times slower than real time since DDT gets 
control after each user instruction is executed. Interrupt processing routines 
can be traced, but it must be noted that commands which use the breakpoint 
facihty (G, T, and U) accomplish the break using a RST 7 instruction, which 
means that the tested program cannot use this interrupt location. Further, 
the trace mode always runs the tested program with interrupts enabled, 
which may cause problems if asynchronous interrupts are received during 
tracing. 

Note also that the operator should use the rubout key to get control back to 
DDT during trace, rather than executing a RST 7, in order to ensure that the 
trace for the current instruction is completed before interruption. 
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The U (Untrace) Command 

The U command is identical to the T command except that intermediate 
program steps are not displayed. The untrace mode allows from 1 to 65535 
(OFFFFH) steps to be executed in monitored mode, and is used principally to 
retain control of an executing program while it reaches steady state 
conditions. All conditions of the T command apply to the U command. 

The X (Examine) Command 

The X command allows selective display and alteration of the current CPU 
state for the program under test. The forms are 

X 

Xr 

where r is one of the 8080 CPU registers 



c 


Carry Flag 


(0/1) 


z 


Zero Flag 


(0/1) 


M 


Minus Flag 


(0/1) 


E 


Even Parity Flag 


(0/1) 


I 


Interdigit Carry 


(0/1) 


A 


Accumulator 


(0-FF) 


B 


BC register pair 


(0-FFFF) 


D 


DE register pair 


(0-FFFF) 


H 


HL register pair 


(0-FFFF) 


S 


Stack Pointer 


(0-FFFF) 


P 


Program Counter 


(0-FFFF) 



In the first case, the CPU register state is displayed in the format 

CfZfMfEflf A = bb B=dddd D=dddd H=dddd S = dddd P = dddd inst 

where f is a or 1 flag value, bb is a byte value, and dddd is a double byte 
quantity corresponding to the register pair. The "inst" field contains the 
disassembled instruction which occurs at the location addressed by the CPU 
state's program counter. 

The second form allows display and optional alteration of register values, 
where r is one of the registers given above (C, Z, M, E, I, A, B, D, H, S, or P). 
In each case, the flag or register value is first displayed at the console. The 
DDT program then accepts input from the console. If a carriage return is 
typed, then the flag or register value is not altered. If a value in the proper 
range is typed, then the flag or register value is altered. Note that EC, DE, 
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and HL are displayed as register pairs. Thus, the operator types the entire 
register pair when B, C, or the BC pair is altered. 

Implementation Notes 

The organization of DDT allows certain non-essential portions to be 
overlayed in order to gain a larger transient program area for debugging large 
programs. The DDT program consists of two parts: the DDT nucleus and 
the assembler/disassembler module. The DDT nucleus is loaded over the 
Console Command Processor, and, although loaded with the DDT nucleus, 
the assembler/disassembler is overlayable unless used to assemble or 
disassemble. 

In particular, the BDOS address at location 6H (address field of the JMP 
instruction at location 5H) is modified by DDT to address the base location 
of the DDT nucleus which, in turn, contains a JMP instruction to the BDOS. 
Thus, programs which use this address field to size memory see the logical 
end of memory at the base of the DDT nucleus rather than the base of the 
BDOS. 

The assembler/disassembler module resides directly below the DDT 
nucleus in the transient program area. If the A, L, T, or X commands are used 
during the debugging process then the DDT program again alters the address 
field at 6H to include this module, thus further reducing the logical end of 
memory. If a program loads beyond the beginning of the 
assembler /disassembler module, the A and L commands are lost (their use 
produces a "?" in response), and the trace and display (T and X) commands 
list the "inst" field of the display in hexadecimal, rather than as a decoded 
instruction. 

Sample Session 

The following example shows an edit, assemble, and debug for a simple 
program which reads a set of data values and determines the largest value in 
the set. The largest value is taken from the vector, and stored into "LARGE" 
at the termination of the program 



ED SCAM.ftSH 

^l /^^ character mbout ^^^^ ^^^ 

ti ORG ri leen l.l Tstart of trahsient area 

HVl B.LEH "length OF VECTOR TO SCAN 

HVi C^ iLARCER.RST Vf^LUS §Q fftR 

Lftflf — P-O.O.L UQ N>VECT ;BASE OF VECTOR 

LfiflLi^ MOV a^ >Q6T VA|L,Vg 

rubout 1 %S^ X- >LARGER VALUE IR C '^ 

deletes JH^ NFOUND .JUMP IF LARGER VALUE MQT FOl\Hl^ 
characters NEtf LARGEST VALUE. STORE IT TO C 

NOV C. A 
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HFOUND: 



VECT: 

LEH 
LARGE 

rZ ♦B9P 



LOOP: 



NFOUND: 



VECT; 

LEN 
LARGE: 

*E 



INK 
DCR 
JNZ 



H 

i 

LOOP 



TO NEXT ELEHEHT 



HORE TO SCftM? 



FOR ftMQTHgP 



END OF SCAN. STORE C 

HOV A/C ;GET LARGEST VALUE 

STA LARGE 

iHe JL ;R6BQQT 



Create Source ' 
Program — underlined 
characters typed 
by programmer. 



TEST DATA 

EQU f.-VECT iLENGTH 

DS JL 

AM 



■ AJ^i^^ST VALUIS Q^ 6XIT 



ORG laeH 

HVI B>LEH 

Hvi c.e 

LXl N.VECT 

NOV A.N 

SUB C 

JNC NFOUND 

NEB LARGEST VALUE* 

NOV C.A 

INK N ;T0 NEKT ELEHENT 

DCR B ;nORE TO SCAN? 

JNZ LOOP iFOR ANOTHER 

END OF SCAN/ STORE C 

NOV A/C ;GET LARGEST VALUE 

STA LARGE 

JNP e .REBOOT 



iSTART OF TRANSIENT AREA 
iLENGTH OF VECTOR TO SCAN 
/LARGEST VALUE SO FAR 
;BASE OF VECTOR 
;GET VALUE 
'LARGER VALUE IN C? 
;JUNP IF LARGER VALUE NOT FOUND 
STORE IT TO C 



TEST DATA 



DB 
EQU 
DS 
END 



$-VECT ;LENGTH 

1 ^LARGEST VALUE ON EXIT 



-End of Edit 



ASH SCAN ^ ' 

""~~ Start Assembler 

CP/H ASSEMBLER - VER I 8 



ei23 

ee2H USE FACTOR 

END OF ASSEMBLY 

TYPE SCAN PRN 



Assembly Complete — Look at Program Listing 



Code Address 

7 
8188'^ Machine Code 
8188 8688 J 

8E88^ 

2U981 

7E 

91 

D28DB1 



8182 
8184 
8187 
8188 
8189 



818C 4F 
818D 23 
818E 85 
818F C28781 



( 



Source Program 



LOOP. 



NFOUND: 



ORG 
MVI 
MVI 
LXI 
MOV 
SUB 
JNC 
NEU 
MOV 
IHX 
DCR 
JNZ 



laeH 

B. LEN 

C. 8 

H, VECT 
A. M 
C 
NFOUND 

LARGEST VALUE. 
C. A 



START OF TRANSIENT AREA 
LENGTH OF VECTOR TO SCAN 
LARGEST VALUE SO FAR 
BASE OF VECTOR 
GET VALUE 

LrtRGER VALUE IN C? 
JUMP IF LARGER VALUE NOT FOUND 
STORE IT TO C 



H 
B 
LOOP 



TO NEXT 
MORE TO 



ELEMENT 
SCAN? 



FOR ANOTHER 



8112 79 

8113 322181 
8116 C38888 

Code /data listing ; 

truncated ► * 

8119 8288848385VECT: 



END OF SCAN. STORE C 

MOV A> C .GET LARGEST VALUE 

STA LARGE 

JMP e . REBOOT 

TEST DATA 

DB 2, 8. 4. 3.S> 6. 1» 5 
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8888 « '^ LEH EQU $-VECT , LENGTH 

ei21 Valueof) LARGE: DS l , LARGEST VALUE ON EXIT 

9^22 Equate' END 

A> 

DDT SCAN. HEX 

*""~"~~* Start Debugger using hex format machine code 

16K DDT VER i. 8 
NEXT PC 
8121 8888 



• last load address + 1 ^ next instruction 

/ to execute at 
C828H8E8I8 A-88 B«8888 D>B88e H»e88e Ss8188 P»888d OUT 7F PC=0 
-XP \ 

^"^ Examine registers before debug run 
P»e8d8 188 

Change PC to 100 

'— Look at registers again /" PC changed 

C028M8E8I8 A=:88 B»8888 D»808e H = 8e8d Ss0188 P°8ie8 NVI B/BS**-^ 
' *• ^^^ Mext instruction ^ 

to execute at PC =100 



6186 


HVI 


6.08 


V 


B182 


HVI 


C.08 


J 


0184 


LXI 


H.8119 


J 


8187 


NOV 


A.H 1 


1 Disassembled Machine 


8188 


SUB 


C ' 


I CodeatlOOH 


8189 
818C 
818D 


JNC 
NOV 
INX 


818D 
C, A 
H 


> (See Source Listing 
1 for comparison) 


?18E 


DCR 


6 


1 


d'lBF 


JN2 


0107 


1 


81 12 
-L. 


MOV 


A,C 


^ 


6113 


STA 


8121 


\ 


81 16 


JNP 


0888 


j 


81 19 
61 lA 


STAX 
NOP 


6 


1 A little more 
r machine code 


01 IB 
01 IC 
011D 
011E 


INR 
INX 
DCR 
NVI 


B 
B 
B 
B.81 


I (note that Program 
/ ends at location 116 
with a JMP to 0000) 


0128 


DCR 


B 




0121 


LXI 


D.2288 




0124 


LXI 


H,8288 > 


/ 


-A116 


ent< 


*r inline assen 


nblv mode to chanae the JA^ 



will cause the program under test to return to DDT if 1 1 6H 
0116 ftST 7 js ever executed. 

8117 (single carriage return stops assembly mode) 

- LI 1 3 List Code at 1 13H to check that RST 7 was property inserted 

- in place of JMP 



81 13 


STA 


0121 


81 16 


RST 


87 mT 


8117 


NOP 




8118 


NOP 




8119 


STAX 


B 


81 lA 


NOP 




81 16 


INR 


B 


811C 


INX 


B 



"iL Look at registers 

C828n8E8I8 A>88 B»8888 D^BBBB H»8888 S*8188 P»8188 NVI 6.88 

"^ Execute Program for one step. initial CPU state, before / is executed 

C8Z8N8E8I8 A»88 B»8888 D-8888 Hs8888 S-8188 P^BIBB NVI 6.88*8182 

"" Trace one step again (note 08H in B) automatic breakpoint ^ 

C828n8E8I8 A«88 6«8888 D«8888 H-8888 S«8188 P>8182 NVI C. 88*8184 
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Trace again (Register C is cleared) 

cezBMeEeie A=8e B=e8Be D^aeee H^eeee $=0100 p=0184 lxi h.0ii9«8ib7 

"— Trace three steps 

cazeweEBie ^=00 6=0300 D-0000 h=0ii9 3=0100 p=0i07 nov a.h 

C0Z0H0E8I0 A»02 B-0800 D»8000 H»0n9 3 = 0100 P»0108 SUB C 
CBZBHBEeil AsB2 8 = 8880 D«0000 H = 01 19 3 = 0100 Ps0109 JNC 010D*010D 
- Ul l Display memon^^tarting at 1 19H. ^^^^^^^.^ ^^^^^.^^ ^^ ^^^^ ^ 

VMdlJ^ '' '' '"^ '' eD^^^g^^^^.d^^^ ^ Lowercasex ^^^ 

0120VJI5/11 00 22 21 00 02 7E EB 77 13 23 EB 0B ^8) Bl . . . ■ !. V iTT^O 

At7A r9 97 a< r-? a? o a ckA aa aa aa aa aa aa a«. >)rX ». , . >^ 

Data is displayed 



0138 C2 27 81 C3 03 29 00 00 00 00 00 00 00 00 00 08 
0140 00 00 00 00 00 88 80 88 80 00 00 00 00 00 00 80 
8158 88 88 88 88 00 00 00 00 00 00 00 00 00 08 00 60 

?!!! ?! ?? ®® ®® ^^ ®® ®® ^® ®® ®® ^® ®® ^® ®® ®® ®® !n7iSCirwith'a"0" 

in the position of 



nongraphic 
characters 



C0Z0i10E0Il (i»92 B»8888 D«8800 H = 01 19 3b0100 Pa010D INK H 



8170 00 00 00 08 00 00 0e 00 00 00 80 00 00 

0180 08 80 88 88 00 00 00 00 08 88 88 88 88 80 00 08 

8198 80 88 88 88 88 88 88 88 88 88 88 88 80 88 88 80 

eiAB 88 80 88 88 88 88 80 88 80 88 88 88 88 88 88 80 

8168 88 88 80 00 00 00 00 00 00 00 00 00 00 00 ee 00 

01C0 00 00 00 00 00 00 08 00 00 00 00 00 00 08 88 80 
'ii. Current CPU state 

COZ 

"II 

Trace 5 steps from current CPU state 

COZOnOEOIl A»02 6 = 0888 D-8888 H*0]19 3 = 0100 P=010D I NX H 

COZOHOEOll A = 02 6 = 0888 D = 8888 H = 01 lA 3 = 0100 P=010E BCR B Automatic 

COZOHOEOIl A = 02 6 = 0700 D=8OO0 H = 01 lA 3=0100 P=0ieF JN2 1 7 Breakpoint 

COZOMOEOIl A=02 6=0700 D=0OO8 H=811A 3«8188 P=8187 MOV A> H I 

C8Z8HBE0Ii A=80 6=8788 D«8888 H=811A 3«8180 P=8188 SUB 0*0109/ 

-u5 viy 

Trace without listing intermediate states 
COZIHOEIII A=0O 6=0700 D«0OOO H"01 lA 3>010O P=0109 JNC 010B*O1O8 
"i CPU State at end of U5 \ 

COZOH0E111 A=04 6=0600 D=8000 H=011B 3=0180 P«0108 SUB C 
~ G_ Run program from current PC until completion (in real-time) 

breakpoint at 1 16H, caused by executing RST 7 in machine code 
• 0116 
-X 
"" CPU state at end of program 

COZINOEIII A=0O 6=0000 D=8888 H=8121 3=8108 P=8116 RST 87 

— examine and change program counter 
P«0116 100 



COZinOElIl A = 80 6 = 8000 = 8008 H = 0121 3 = 8100 p:=8180 NVI 6.08 

-lis Trace 10 (hexadecimal), steps , ^"^^^ ^°'" ^on^Parison 

first data element cunrent largest value 

CeZlNOElll A = e0 6 = 0000 D = e^40 H = 0121 S^^t>« P = 0108 MVI 

COZIHOEIII A = 00 6 = 0800 D^^OO H = 81>*^=8108 P = 8102 NVI 

COZlMOElll A = 00 8 = 0805^=8000 H^^«l21 3 = 0180 P = 0ie4 LXI 

C8Z1M8E1I1 A = e0 e^Orfgl D=>8'^V^=ei 19 3 = 0100 P=ei07 H( 

COZIHOEIII A^gi^^OaiU-ir^OOO H = 0119 3 = 0100 P = 0103 31 
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cezeneEei i 


A«e2 


B^esee D»eeee 


H 


cezeneEeii 


A«e2 


B=e8ee D^eeee 


H 


cezeneEeii 


A«B2 


Bxeeee D»eeee 


H 


cezeMBEeii 


A = 82 


B=e7Be D=eeee 


H 


cezeHBEeii 


A=e2 


B=87B6 D^eeee 


H 


cezeneEeii 


A^ee 


8=9789 D=e89e 


H 


CeZlUBElIl 


(^»ee 


8=9788 D=ee89 


H 


ceziHeEiii 


A»ee 


8=8788 D=8888 


H 


ceziMeEiii 


A^^ee 


8=8788 0=8988 


H 


cezeHeEiii 


A=ee 


8=9688 D=8888 


H 


cezeneEii i 


A=ee 


8=8688 0=8989 


H 


-Aies 


Insert a "hot patch" into 


eies JC leD the machine code 
to change the 

eiec JNCtoJC 





eiBD 



s= 




Program should have moved the 
value from A into C since A>C. 
Since this code was not executed, 
it appears that the JNC should 
have been a JC instruction 
" £S Stop DDT so that a'version of 

the patched program can be saved 

SftVE 1 SCAN COH Program resides on first page, so save 1 page, 

A > DDT SCAN. COH Restart DDT with the saved memory image to continue testing 



i6K DDT VER 1. 9 


NEXT 


PC 




B2ee 


Biee 




-Liee 




List some code 


Biee 


MVI 


B.88 


eie2 


HVI 


. c. ee 


0184 

Bie? 


LXI 


H.8119 


HOV 


A.M y 


eies 


SUB 


^ y^ 


eies 


JC 


818I> 


eiec 


nov 


L, (i 


BieD 


I NX 


H 


81 BE 


DCR 


8 


eiBF 


JNZ 


8187 


8112 


HOV 


A. C 


"IL 






p=eie8 





Previous patch is present in XCOM 



- TIB Trace to see how patched version operates 



Data Is moved from A to C 



cezenBEBie 


A = 8B 


6=8988 


D=e999 


H=999« 


i = 9l99^ 


/<=9199 


nvi 


B>B8 


cezenBEBie 


A = 8B 


8=8888 


D=8B99 


H=9999 


S = 91jBf 


P=9192 


nvi 


CBB 


CeZBHBEeid 


A = 8B 


8=8889 


D=B888 


H=9998 


S^^9 9 


P=9184 


LXI 


H . B 11 9 


cezenBEBie 


c> = 8B 


8=8888 


D=8888 


H=91 19, 


^9199 


P=9187 


nov 


A. n 


cezBnBEBie 


A^T^ 


4^=8888 


0=8889 


H = eu< 


S=ei99 


P=ai98 


SUB 


r 


cezenBEBi i 


A = e2 


8^88 8 


D = e8ajB^ 


"Jm^^is 


S=9199 


P=9199 


JC 


8180 


cezenBEBi i 


A = 82 


B = B^Me 


D»«<88 


H=91 19 


S=9199 


P=ei9C 


nov 


C A 


CBZBnBEBI 1 


A = 82 


8 = 8^?|) 


0=8888 


H = 81 19 


i=ei99 


P=9190 


INX 


H 


cezenBEBi i 


A=82 


8=6882 


0=8888 


H = 91 lA 


$=9199 


P=919E 


OCR 


8 


CeZBHBEeil 


A = 82 


8=8782 


0=8888 


H = 91 lA 


S=919e 


P=818F 


JNZ 


9187 


cezenBEBi i 


A = 82 


8=8782 


0=8999 


H = 91 lA 


S=9199 


P=9197 


nov 


A. n 


CBZBnBEBI 1 


A = 8e 


B=8782 


0=8999 


H = 91 lA 


^=9189 


P=9198 


SUB 


c 


ClZBniEBIB 


A = FE 


8=8782 


0=8898 


H=ei lA 


$=9199 


P=9199 


JC 


8180 


ClZBniEBIB 


A = FE 


8=8782 


0=8999 


H = 91 lA 


$=9199 


P=919D 


INX 


H 


cizeniEBie 


A = FE 


8=8782 


0=8888 


H = 9 1 1 B 


$=9199 


P=B19E 


OCR 


8 


cizenBEii 1 


A = FE 


8=8682 


0=8889 


H = ei IB 


S=9199 


P=918F 


JNZ 


8187*8187 


-X. 












breakpoint after 16 steps --^ 


ClZBnBElI 1 


A = FE 


9=9692 


0=8999 


H = ei IB 


^=9199 


P=8187 


nov 


A, n 


- G . 1 9 8 Run from cun-ent PC and breakpoint at 108H 








*eie8 


















-JC. 


^ 


- next data item 













r 



ctzeneEiii a=84 e-eses o^eeea H-eiiB s=eiee p-eies sub c 
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•" Single step for a few cycles 

cizeneEiii A=e4 6=8bd2 D=B8ee H = eii6 s^eiee p^^eiea sue 



C^eidd 



cezeneEei ; 

-X 



« = e2 8 = 6662 D = ee88 H = eilB i. = 818e P = 8189 JC 



CezeH8E6Il A = 82 8=^8682 D-8888 H = 811B S==8188 P»818C HOV 
— Run to completion 



818D*818C 



:. A 



*8116 
-X. 

CeZinSElIl A»83 8=^8883 = 888 
'1111 look at the value of -LARGE* 

8121 8 3 Wrong Value! 

8122 88 



H=8121 



=6188 P«8116 RSI 87 



8123 


22 






8124 


21 






8125 


88 






812b 
CM 27 


. . - End of the S command 


-Liee 








81de 


MVI 


B. 83 N 




9182 


MVI 


C.88 




8184 


LXI 


H.8119 




8187 


MOV 


A,. M 




8188 


SUB 


C 




8189 


JC 


818D 




ei8C 


MOV 


C. A 




818D 


I NX 


H 




818E 


DCft 


B 




eiep 


JNZ 


8187 




81 12 


MOV 


A.C 


> Review the code 


81 13 


STA 


8121 




81 16 


RST 


87 




8117 


NOP 






81 18 


NOP 






e>i 19 


STAX 


B 




01 lA 


NOP 






81 16 


INR 


B 




8 1 I C 


I NX 


B 




1 1 D 


DCR 


B 




1 I E 


MVI 


6. 81 




8128 


DCR 


B J 




-aP 








P=8116 188 


Reset the 


PC 



■J. Single step, and watch data values 

CdZlMBElIl A = 83 8 = 8883 D = 8888 H=:8121 

C8Z1M8E111 A=83 8^8883 D=8888 H=8121 
- T count set 

" / ^ — largest set 

C8Z1M8E1I1 ^=83 6=8888 D=8e88 H=8121 
-T 



•S = 9188 P=8188 MVI B.83»8182 
S=818G P=8182 MVI C.88*8184 
S = 8188 P-8 184 LXI H- Pill 9*8 18 7 
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^ base address of data set 

ceziMBEJii R=e3 B-=tf8ee D = ee«ee H = eii9 s^eiwy p:--enii7 hov «.ri*Bie8 

-T_ 

^ first data item brought to A 

ceziMeEiii A=e2 B=edee D=eeee h=0ii9 §=0180 p=0i08 sub 0*0109 

-X 

C0ZC1I10E0II « = 02 B-0800 ri=0000 H = 0U9 S = 0100 P=0ie*3 JC 010D*010C 

C020I10E0I1 H = 02 = 0800 D=0000 H = 0119 S = 0100 P=0I0C HOV C..A*010D 
"~ / first data item moved to C correctly 

C02eM0E0Il A»02 6^0802 D=0000 H = 0M9 S = 0100 P=010D I NX H*010E 

-1 

C0Z0tt0E01l ^ = 02 B = 0802 D = 0000 H = 0MA S=0100 P«010E DCR B^BIOF 
C020f10E01l A = 02 B = 0702 D = 0000 H = 011A S=0100 P = 010F JNZ 0107*0107 

C0Z0M0E011 H = 02 & = 0702 D=e00y H = ig1 l H r-^i ^t. Ps^lb? '^OV t4,fl*0ie8 

— y^ second data item brought to A 

C020M0E0I1 H=00 B=0702 D=0000 H=011A S=0100 P«0108 SUB C*0189 

— /- subtract destroys data value which was loaded!!! 

C1Z0M1E0I0 « = FE B-=0702 D=0000 H = 011A S = 0100 P = 0109 JC 010D*010D 

i:i20MlE0I0 A = FE 6^0702 D = 0000 H = 011ft i = 0100 P=010D I NX H*010E 
- L100 

0100 tlVI B.0d 

102 M VI C. 

0104 LXl H,0119 

0107 MOV A,H 

0108 SUB C < This should have been a CMP so that register A 

0109 JC 010D would not be destroyed. 
010C MOV C. rt 

10H I NX H 
010E DCR B 
010F JNZ 0107 
0112 HOV A. C 

- M 1 8 

"i" 1 8 CHP C hot patch at 1 08H changes SUB to CMP 

01 09 

- b0i stop DDT for SAVE 
SmVE 1 SCAN COM 



save memory image 
M >DDT SCAN. COH Restart DDT 

UK DDT VEft 10 
NEXT PC 
0200 0100 
-XF 

P=0100 
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- L116 

0116 RST e? 

0117 NOP 

0118 NOP > ^-^^^ 3^ code to see if It was properiy loaded 

0119 STAXB ( ^'°"9 typeout aborted with mbout) 
011A NOP 
~ (rubout) 

- G- 1 Ig Run from lOOH to completion 

♦0116 

- XC Look at Carry (accidental typo) 

C 1 

-£ Look at CPU state 

ClZlfieElIl A=06 B = 00efc": D=9000 H = 0121 i.= 0100 P=011t" RST 07 
-'-121 
•' Look at "Large" — it appears to be con-ect. 

0121 06 

0122 00 

0123 22 . 

- G0 stop DDT 



ED SCftN^t^SH Re-edit the source program, and make both changes 

*0LT /CtIZ 



SUB / C 

^^cmT^ c 



.LARGER VALUE IN C' 
-LARGER VALUE IN C' 



JNC NFOUNIi ,JU«P IF LARGER VALUE NOT FOUND 

■♦ SNCyZKiyZl0LT 

JC HFOUND ,.JUMP IF LARGER VALUE MOT FOUND 

*^ 

hSW scan, a at Re-assemble, selecting source from disk A 

hex to disk A 
CP/M ASSEMBLER - VER 1 print to Z (selects no print file) 

0122 

002H USE FACTOR 

END OF ASSEMBLY 

DDF SCAN HEX Re-mn debugger to check changes 

:6K DDT VER 1. 
HEXT PC 

0121 0000 

-L116 

sjilb J MP 000 check to ensure end is still at 11 6H 
0119 S T A X B 
011 A NOP 
011B INR B 
■ (rubout) 

- G 1 ■' 1 It Go from beginning with breakpoint at end 
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t 8 1 1 li breakpoint reached 

"iLLLL Look at '*L^RGE^;__ correct value computed 

ei2i (e^Teo £2 21 00 e2 7e eb ?? 13 23 eb eB 78 bi . " 

•>l?0 C£ 2? Pfl C3 y3 23 Se 08 89 oe 00 60 60 0i? 80 88 
••:U4e 8 00 80 8 08 88 8 8 8 8 8 8 88 88 8 

- (rubout) aborts long typeout 

- £8^ stop DDT. debug session complete 



.) . . . 



141 



CP/M 2.2 ALTERATION GUIDE 



COPYRIGHT (c) 1979 
DIGITAL RESEARCH 



Copyright 

Copyright (c) 1979 by Digital Research. All rights re- 
served. No part of this publication may be reproduced, 
transmitted, transcribed, stored in a retrieval system, or 
translated into any language or computer language, in 
any form or by any means, electronic, mechanical, mag- 
netic, optical, chemical, manual or otherwise, without 
the prior written permission of Digital Research, Post 
Office Box 579, Pacific Grove, California 93950. 

Disclaimer 

Digital Research makes no representations or warranties 
with respect to the contents hereof and specifically 
disclaims any implied warranties of merchantability or 
fitness for any particular purpose. Further, Digital 
Research reserves the right to revise this publication 
and to make changes from time to time in the content 
hereof without obligation of Digital Research to notify 
any person of such revision or changes. 

Trademarks 

CP/M is a registered trademark of Digital Research. 
MP/M, MAC, and SID are trademarks of Digital 
Research. 



(AU Information Contained Herein is Proprietary to Digital Research.) 
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Introduction 

The standard CP/M system assumes operation on an Intel MDS-800 
microcomputer development system, but is designed so that the user can 
alter a specific set of subroutines which define the hardware operating 
environment. In this way, the user can produce a diskette which operates 
with any IBM-3741 format compatible drive controller and other peripheral 
devices. 

Although standard CP/M 2.2 is configured for single density floppy disks, 
field-alteration features allow adaptation to a wide variety of disk 
subsystems from single drive minidisks through high-capacity "hard 
disk" systems. In order to simplify the following adaptation process, we 
assume that CP/M 2.2 will first be configured for single density floppy 
disks where minimal editing and debugging tools are available. If an 
earlier version of CP/M is available, the customizing process is eased 
considerably. In this latter case, you may wish to briefly review the 
system generation process, and skip to later sections which discuss 
system alteration for non-standard disk systems. 

In order to achieve device independence, CP/M is separated into three 
distinct modules: 

BIOS — basic I/O system which is environment dependent 
BDOS — basic disk operating system which is not dependent upon 

the hardware configuration 
CCP — the console command processor which uses the BDOS 

Of these modules, only the BIOS is dependent upon the particular 
hardware. That is, the user can "patch" the distribution version of CP/M 
to provide a new BIOS which provides a customized interface between the 
remaining CP/M modules and the user's own hardware system. The 
purpose of this document is to provide a step-by-step procedure for 
patching your new BIOS into CP/M. 

If CP/M is being tailored to your computer system for the first time, the 
new BIOS requires some relatively simple software development and 
testing. The standard BIOS is listed in Appendix B, and can be used as a 
model for the customized package. A skeletal version of the BIOS is given 
in Appendix C which can serve as the basis for a modified BIOS. In 
addition to the BIOS, the user must write a simple memory loader, called 
GETSYS, which brings the operating system into memory. In order to 
patch the new BIOS into CP/M, the user must write the reverse of 
GETSYS, called PUTSYS, which places an altered version of CP/M back 
onto the diskette. PUTSYS can be derived from GETSYS by changing the 
disk read commands into disk write commands. Sample skeletal GETSYS 
and PUTSYS programs are described in Section 3, and listed in Appendix 
D. In order to make the CP/M system work automatically, the user must 
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also supply a cold start loader, similar to the one provided with CP/M 
(listed in Appendices A and B). A skeletal form of a cold start loader is 
given in Appendix E which can serve as a model for your loader. 

First Level System Regeneration 

The procedure to follow to patch the CP/M system is given below in 
several steps. Address references in each step are shown with a following 
"H** which denotes the hexadecimal radix, and are given for a 20K CP/M 
system. For larger CP/M systems, add a "bias" to each address which is 
shown with a "+b" following it, where b is equal to the memory size — 
20K. Values for b in various standard memory sizes are 



24K 
32K 

40K 
48K 
56K 
62K 
64K 



b = 24K - 20K = 4K = lOOOH 
b = 32K - 20K = 12K = 3000H 
b = 40K - 20K = 20K = 5000H 
b = 48K - 20K = 28K = 7000H 
b = 56K - 20K = 36K = 9000H 
b = 62K - 20K = 42K = A800H 
b = 64K - 20K = 44K = BOOOH 



Note: The standard distribution version of CP/M is set for operation 
within a 20K memory system. Therefore, you must first bring up the 20K 
CP/M system, and then configure it for your actual memory size (see 
Second Level System Generation). 

( 1 ) Review Section 4 and write a GETSYS program which reads the first 
two tracks of a diskette into memory. The data from the diskette 
must begin at location 3380H. Code GETSYS so that it starts at 
location lOOH (base of the TPA), as shown in the first part of 
Appendix d. 

( 2 ) Test the GETSYS program by reading a blank diskette into memory, 
and check to see that the data has been read properly, and that the 
diskette has not been altered in any way by the GETSYS program. 

( 3 ) Run the GETSYS program using an initialized CP/M diskette to see 
if GETSYS loads CP/M starting at 3380H (the operating system 
actually starts 128 bytes later at 3400H). 

(4) Review Section 4 and write the PUTSYS program which writes 
memory starting at 3380H back onto the first two tracks of the 
diskette. The PUTSYS program should be located at 200H, as shown 
in the second part of Appendix D. 

(5) Test the PUTSYS program using a blank uninitialized diskette by 
writing a portion of memory to the first two tracks; clear memory and 
read it back using GETSYS. Test PUTSYS completely, since this 

146 



program will be used to alter CP/M on disk. 

(6) Study Sections 5, 6, and 7, along with the distribution version of the 
BIOS given in Appendix B, and write a simple version which performs 
a similar function for the customized environment. Use the program 
given in Appendix C as a model. Call this new BIOS by the name 
CBIOS (customized BIOS). Implement only the primitive disk 
operations on a single drive, and simple console input/output 
functions in this phase. 

(7) Test CBIOS completely to ensure that it properly performs console 
character I/O and disk reads and writes. Be especially careful to 
ensure that no disk write operations occur accidently during read 
operations, and check that the proper track and sectors are addressed 
on all reads and writes. Failure to make these checks may cause 
destruction of the initialized CP/M system after it is patched. 

(8) Referring to Figure 1 in Section 5, note that the BIOS is placed 
between locations 4A00H and 4FFFH. Read the CP/M system using 
GETSYS and replace the BIOS segment by the new CBIOS developed 
in step (6) and tested in step (7). This replacement is done in the 
memory of the machine, and will be placed on the diskette in the next 
step. 

(9) Use PUTSYS to place the patched memory image of CP/M onto the 
first two tracks of a blank diskette for testing. 

(10) Use GETSYS to bring the copied memory image from the test 
diskette back into memory at 3380H, and check to ensure that it has 
loaded back properly (clear memory, if possible, before the load). 
Upon successful load, branch to the cold start code at location 
4A00H. The cold start routine will initialize page zero, then jump to 
the CCP at location 3400H which will call the BDOS, which will call 
the CBIOS. The CBIOS will be asked by the CCP to read sixteen 
sectors on track 2, and if successful, CP/M will type "A ", the 
system prompt. 

When you make it this far, you are almost on the air. If you have 
trouble, use whatever debug facilities you have available to trace and 
breakpoint your CBIOS. 

( 11 ) Upon completion of step ( 10), CP/M has prompted the console for a 
command input. Test the disk write operations by typing 

SAVE 1 X.COM 

(recall that all commands must be followed by a carriage return). 
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CP/M should respond with another prompt (after several disk 
accesses): 

A 

If it does not, debug your disk write functions and retry. 

( 12) Then test the directory command by typing 

DIR 
CP/M should respond with 
A: X COM 

( 13) Test the erase command by typing 

ERA X.COM 

CP/M should respond with the A prompt. When you make it this far, 
you should have an operational system which will only require a 
bootstrap loader to function completely. 

( 14) Write a bootstrap loader which is similar to GETSYS, and place it on 
track 0, sector 1 using PUTSYS (again using the test diskette, not 
the distribution diskette). See Sections 5 and 8 for more information 
on the bootstrap operation. 

(15) Retest the new test diskette with the bootstrap loader installed by 
executing steps (11), (12), and (13). Upon completion of these tests, 
type a control-C (control and C keys simultaneously). The system 
should then execute a "warm start" which reboots the system, and 
types the A prompt. 

(16) At this point, you probably have a good version of your customized 
CP/M system on your test diskette. Use GETSYS to load CP/M 
from your test diskette. Remove the test diskette, place the 
distribution diskette (or a legal copy) into the drive, and use PUTSYS 
to replace the distribution version by your customized version. Do 
not make this replacement if you are unsure of your patch since this 
step destroys the system which was sent to you from Digital 
Research. 

( 17) Load your modified CP/M system and test it by typing 

DIR 
CP/M should respond with a list of files which are provided on the 
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initialized diskette. One such file should be the memory image for the 
debugger, called DDT.COM. 

NOTE: from now on, it is important that you always reboot the CP/M 
system (ctl-C is sufficient) when the diskette is removed and replaced by 
another diskette, unless the new diskette is to be read only. 

( 18) Load and test the debugger by typing 

DDT 

(see the document "CP/M Dynamic Debugging Tool (DDT)" for 
operating procedures. You should take the time to become familiar 
with DDT, it will be your best friend in later steps. ) 

( 19 ) Before making f uther CBIOS modifications, practice using the editor 
(see the ED user's guide), and assembler (see the ASM user's guide). 
Then recode and test the GETSYS, PUTSYS, and CBIOS programs 
using ED, ASM, and DDT. Code and test a COPY program which 
does a sector-to-sector copy from one diskette to another to obtain 
back-up copies of the original diskette (NOTE: read your CP/M 
Licensing Agreement; it specifies your legal responsibilities when 
copying the CP/M system). Place the copyright notice 

Copyright (c), 1979 
Digital Research 

on each copy which is made with your COPY program. 

(20) Modify your CBIOS to include the extra functions for pimches, 
readers, signon messages, and so-forth, and add the facilities for 
additional disk drives, if desired. You can make these changes with 
the GETSYS and PUTSYS programs which you have developed, or 
you can refer to the following section, which outlines CP/M facilities 
which will aid you in the regeneration process. 

You now have a good copy of the customized CP/M system. Note that 
although the CBIOS portion of CP/M which you have developed belongs 
to you, the modified version of CP/M which you have created can be 
copied for your use only (again, read your Licensing Agreement), and 
cannot be legally copied for anyone else's use. 

It should be noted that your system remains file-compatible with all other 
CP/M systems, (assuming media compatibility, of course) which allows 
transfer of non-proprietary software between users of CP/M. 
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Second Level System Generation 

Now that you have the CP/M system running, you will want to configure 
CP/M for your memory size. In general, you will first get a memory image 
of CP/M with the "MOVCPM" program (system relocator) and place this 
memory image into a named disk file. The disk file can then be loaded, 
examined, patched, and replaced using the debugger, and system 
generation program. For further details on the operation of these programs, 
see the "Guide to CP/M Features and Facilities" manual. 

Your CHIOS and BOOT can be modified using ED, and assembled using 
ASM, producing files called CBIOS.HEX and BOOT.HEX, which contain 
the machine code for CBIOS and BOOT in Intel hex format. 

To get the memory image of CP/M into the TPA configured for the desired 
memory size, give the command: 

MOVCPM XX * 

where "xx" is the memory size* in decimal K bytes (e.g., 32 for 32K). The 
response will be: 

CONSTRUCTING xxK CP/M VERS 2.0 
READY FOR "SYSGEN" OR 
"SAVE 34 CPMxx.COM" 

At this point, an image of a CP/M in the TPA configured for the requested 
memory size. The memory image is at location 0900H through 227FH. 
(i.e., The BOOT is at 0900H, the CCP is at 980H, the BDOS starts at 
1180H, and the BIOS is at 1F80H. ) Note that the memory image has the 
standard MDS-800 BIOS and BOOT on it. It is now necessary to save the 
memory image in a file so that you can patch your CBIOS and CBOOT 
into it: 

SAVE 34 CPMxx.COM 

The memory image created by the "MOVCPM" program is offset by a 
negative bias so that it loads into the free area of the TPA, and thus does 
not interfere with the operation of CP/M in higher memory. This memory 
image can be subsequently loaded under DDT and examined or changed in 
preparation for a new generation of the system, DDT is loaded with the 
memory image by typing: 

DDT CPMxx.COM Load DDT, then read the CPM 

image 
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DDT should respond with 

NEXT PC 

2300 0100 

— (The DDT prompt) 

You can then use the display and disassembly commands to examine 
portions of the memory image between 900H and 227FH. Note, however, 
that to find any particular address within the memory image, you must 
apply the negative bias to the CP/M address to find the actual address. 
Track 00, sector 01 is loaded to location 900H (you should find the cold 
start loader at 900H to 97FH ), track 00, sector 02 is loaded into 980H (this 
is the base of the CCP ), and so-f orth through the entire CP/M system load. 
In a 20K system, for example, the CCP resides at the CP/M address 
3400H, but is placed into memory at 980H by the SYSGEN program. 
Thus, the negative bias, denoted by n, satisfies 

3400H + n = 980H, or n = 980H - 3400H 

Assuming two's complement arithmetic, n = D580H, which can be 
checked by 

3400H + D580H = 10980H = 0980H ignoring high-order 

overflow). 

Note that for larger systems, n satisfies 

(3400H+b) + n = 980H, or 
n = 980H - (3400H + b), or 
n = D580H - b. 

The value of n for common CP/M systems is given below 

memory size bias b negative offset n 

D580H - OOOOH = D580H 
D580H - lOOOH = C580H 
D580H - 3000H = A580H 
D580H - 5000H = 8580H 
D580H - 7000H = 6580H 
D680H - 9000H = 4580H 
D580H - A800H = 2D80H 
D580H - BOOOH = 2580H 

Assimie, for example, that you want to locate the address x within the 
memory image loaded under DDT in a 20K system. First type 

Hx,n Hexadecimal sum and difference 
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20K 


OOOOH 


24K 


lOOOH 


32K 


3000H 


40K 


5000H 


48K 


7000H 


56K 


9000H 


62K 


A800H 


64K 


BOOOH 



and DDT will respond with the value of x+n (sum) and x— n (difference). 
The first number printed by DDT will be the actual memory address in the 
image where the data or code will be found. The input 

H3400,D580 

for example, will produce 980H as the sum, which is where the CCP is 
located in the memory image under DDT. 

Use the L command to disassemble portions the BIOS located at 
(4A00H+b)— n which, when you use the H command, produces an actual 
address of 1F80H. The disassembly command would thus be 
L1F80 

It is now necessary to patch in your CBOOT and CHIOS routines. The 
BOOT resides at location 0900H in the memory image. If the actual load 
address is "n", then to calculate the bias (m) use the command: 

H900,n Subtract load address from target 

address. 

The second number typed in response to the command is the desired bias 
(m). For example, if your BOOT executes at 0080H, the command: 

H900,80 

will reply 

0980 0880 Sum and difference in hex. 

Therefore, the bias, "m" would be 0880H. To read-in the BOOT, give the 
command: 

ICBOOT.HEX Input file CBOOT.HEX 

Then: 

Rm Read CBOOT with a bias of 

m(=900H-n) 

You may now examine your CBOOT with: 

L900 

We are now ready to replace the CBIOS. Examine the area at 1F80H where 
the original version of the CBIOS resides. Then t3rpe 

ICBIOS.HEX Ready the "hex" file for loading 
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assume that your CBIOS is being integrated into a 20K CP/M system, 
and thus is originated at location 4A00H. In order to properly locate the 
CBIOS in the memory image under DDT, we must apply the negative bias 
n for a 20K system when loading the hex file. This is accomplished by 
typing 

RD580 Read the file with bias D580H 

Upon completion of the read, re-examine the area where the CBIOS has 
been loaded (use an "L1F80" command), to ensure that it was loaded 
properly. When you are satisfied that the change has been made, return 
from DDT using a control-C or "GO" command. 

Now use SYSGEN to replace the patched memory image back onto a 
diskette (use a test diskette until you are sure of your patch), as shown in 
the following interaction 

SYSGEN Start the SYSGEN program 

SYSGEN VERSION 2.0 

SYSGEN VERSION 2.0 Sign-on message from SYSGEN 
SOURCE DRIVE NAME (OR RETURN TO SKIP) 

Respond with a carriage return to 
skip the CP/M read operation 
since the system is already in 
memory. 
DESTINATION DRIVE NAME (OR RETURN TO REBOOT) 

Respond with "B" to write the new 
system to the diskette in drive B. 
DESTINATION ON B, THEN TYPE RETURN 

Place a scratch diskette in drive B, 
then type return. 
FUNCTION COMPLETE 
DESTINATION DRIVE NAME (OR RETURN TO REBOOT) 

Place the scratch diskette in your drive A, and then perform a coldstart to 
bring up the new CP/M system you have configured. 

Test the new CP/M system, and place the Digital Research copyright 
notice on the diskette, as specified in your Licensing Agreement: 

Copyright (c), 1979 
Digital Research 
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Sample GETSYS and PUTSYS Program 

The following program provides a framework for the GETSYS and 
PUTSYS programs referenced in Section 2. The READSEC and 
WRITESEC subroutines must be inserted by the user to read and write 
the specific sectors. 



GETSYS PROGRAM - READ TRACKS AND 1 TO MEMORY AT 3380H 

USE 
(SCRATCH REGISTER) 
TRACK COUNT (0, 1) 
SECTOR COUNT { 1,2, ... ,26) 
(SCRATCH REGISTER PAIR) 
LOAD ADDRESS 
SET TO STACK ADDRESS 



SET STACK POINTER TO SCRATCH AREA 
SET BASE LOAD ADDRESS 
START WITH TRACK 
READ NEXT TRACK (INITIALLY 0) 
READ STARTING WITH SECTOR 1 
READ NEXT SECTOR 
USER-SUPPLIED SUBROUTINE 
MOVE LOAD ADDRESS TO NEXT 1/2 PAGE 
HL = HL + 128 
SECTOR = SECTOR + 1 
CHECK FOR END OF TRACK 

CARRY GENERATED IF SECTOR 27 



; REGISTER 






A 






B 






C 






DE 






HL 






SP 




START: 


LXI 


SP,3380H 




LXI 


H, 3380H 




MVI 


B,0 


RDTRK: 








MVI 


C,l 


RDSEC: 








CALL 


READSEC 




LXI 


D,128 




DAD 


D 




INR 


C 




MOV 


A.C 




CPI 


27 




JC 


RDSEC 



ARRIVE HERE AT END OF TRACK, MOVE TO NEXT TRACK 
INR B 

MOV A,B ;TEST FOR LAST TRACK 
CPI 2 
JC RDTRK ;CARRY GENERATED IF TRACK 2 

ARRIVE HERE AT END OF LOAD, HALT FOR NOW 
HLT 



; USER-SUPPLIED SUBROUTINE TO READ THE DISK 
READSEC: 

ENTER WITH TRACK NUMBER IN REGISTER B. 
SECTOR NUMBER IN REGISTER C, AND 
ADDRESS TO FILL IN HL 
PUSH B ;SAVE B AND C REGISTERS 
PUSH H ;SAVE HL REGISTERS 



perform disk read at this point, branch to 
label START if an error occurs 



POP 
POP 
RET 



H 
B 



RECOVER HL 

RECOVER B AND C REGISTERS 

BACK TO MAIN PROGRAM 



END START 
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Note that his program is assembled and listed in Appendix C for reference 
purposes, with an assumed origin of lOOH. The hexadecimal operation 
codes which are listed on the left may be useful if the program has to be 
entered through your machine's front panel switches. 

The PUTSYS program can be constructed from GETSYS by changing 
only a few operations in the GETSYS program given above, as shown in 
Appendix D. The register pair HL become the dump address (next address 
to write), and operations upon these registers do not change within the 
program. The READSEC subroutine is replaced by a WRITESEC 
subroutine which performs the opposite function: data from address HL is 
written to the track given by register B and sector given by register C. It is 
often useful to combine GETSYS and PUTSYS into a single program 
during the test and development phase, as shown in the Appendix. 

Diskette Organization 

The sector allocation for the standard distribution version of CP/M is 
given here for reference purposes. The first sector (see table on the follow- 
ing page) contains an optional software boot section. Disk controllers are 
often set up to bring track 0, sector 1 into memory at a specific location 
(often location OOOOH). The program in this sector, called BOOT, has the 
responsibility of bringing the remaining sectors into memory starting at 
location 3400H+b. If your controller does not have a built-in sector load, 
you can ignore the program in track 0, sector 1, and begin the load from 
track sector 2 to location 3400H+b. 

As an example, the Intel MDS-800 hardware cold start loader brings 
track 0, sector 1 into absolute address, 3000H. Upon loading this sector, 
control transfers to location 3000H, where the bootstrap operation 
commences by loading the remainder of track 0, and all of track 1 into 
memory, starting at 3400H+b. The user should note that this bootstrap 
loader is of little use in a non-MDS environment, although it is useful to 
examine it since some of the boot actions will have to be duplicated in your 
cold start loader. 
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Tracks 


Sector# 


Page« 


Memory Address 


CP/M Module name 


00 


01 




(boot address) 


Cold Start Loader 


00 


02 


00 


3400H+b 


CCP 


•t 


03 


II 


3480H+b 


•• 


•4 


04 


01 


3500H+b 


If 


It 


05 


II 


3580H+b 


II 


*f 


06 


02 


3600H+b 


M 


" 


07 


II 


3680H+b 


M 


•• 


08 


03 


3700H+b 


11 


•1 


09 


•1 


3780H+b 


*l 


•1 


10 


04 


3800H+b 


• 1 


II 


11 


t« 


3880H+b 


II 


•1 


12 


05 


3900H+b 


•' 


•« 


13 


It 


3980H+b 


II 


II 


14 


06 


3A00H+b 


■ 1 


II 


15 


*• 


3A80H+b 


• 1 


•1 


16 


07 


3B00H+b 


•I 


00 


17 


ti 


3B80H+b 


CCP 


00 


18 


08 


3C00H+b 


BDOS 


II 


19 


ll 


3C80H+b 


•1 


" 


20 


09 


3D00H+b 


•• 


" 


21 


II 


3D80H+b 


•• 


II 


22 


10 


3E00H+b 


II 


II 


23 


II 


3E80H+b 


ti 


II 


24 


11 


3F00H+b 


*i 


II 


25 


H 


3F80H+b 


•1 


II 


26 


12 


400.0H+b 


I* 


01 


01 


•I 


4080H+b 


II 


II 


02 


13 


4100H+b 


II 


M 


03 


•1 


4180H+b 


ll 


II 


04 


14 


4200H+b 


i« 


ll 


05 


•1 


4280H+b 


M 


II 


06 


15 


4300H+b 


•1 


II 


07 


w 


4380H+b 


•1 


M 


08 


16 


4400H+b 


»l 


II 


09 


•1 


4480H+b 


II 


l« 


10 


17 


4500H+b 


II 


•• 


11 


II 


4580H+b 


•• 


1* 


12 


18 


4600H+b 


M 


•t 


13 


l4 


4680H+b 


M 


I* 


14 


19 


4700H+b 


•• 


«l 


15 


ll 


4780H+b 


II 


•• 


16 


20 


4800H+b 


n 


•I 


17 


11 


4880H+b 


*• 


•• 


18 


21 


4900H+b 


1* 


01 


19 


u 


4980H+b 


BDOS 


01 


20 


22 


4A00H+b 


BIOS 


•I 


21 


•1 


4A80H+b 


II 


M 


23 


23 


4B00H+b 


II 


•t 


24 


ll 


4B80H+b 


II 


H 


25 


24 


4C00H+b 


II 


01 


26 


t* 


4C80H+b 


BIOS 


02-76 


01-26 






(directory and data) 



(All Information Contained Herein is Proprietary to Digital Research.) 
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The Bios Entry Points 

The entry points into the BIOS from the cold start loader and BDOS are 
detailed below. Entry to the BIOS is through a "jump vector" located at 
4A00H+b, as shown below (see Appendices B and C, as well). The jump 
vector is a sequence of 17 jump instructions which send program control to 
the individual BIOS subroutines. The BIOS subroutines may be empty 
for certain functions (i.e., they may contain a single RET operation) 
during regeneration of CP/M, but the entries must be present in the jump 
vector. 

The jump vector at 4A00HH-b takes the form shown below, where the 
individual jump addresses are given to the left: 



4A00H+b 


JMP BOOT 


4A03H+b 


JMP WBOOT 


4A06H + b 


JMP CONST 


4A09H+b 


JMP CONIN 


4A0CH+b 


JMP CONOUT 


4A0FH+b 


JMP LIST 


4Al2H-hb 


JMP PUNCH 


4Al5H + b 


JMP READER 


4Al8H + b 


JMP HOME 


4AlBH+b 


JMP SELDSK 


4AlEH+b 


JMP SETTRK 


4A21H+b 


JMP SETSEC 


4A24H+b 


JMP SETUMA 


4A27H + b 


JMP READ 


4A2AH+b 


JMP WRITE 


4A2DH + b 


JMP LISTST 


4A30H+b 


JMP SECTRAN 



ARRIVE HERE FROM COLD START LOAD 

ARRIVE HERE FOR WARM START 

CHECK FOR CONSOLE CHAR READY 

READ CONSOLE CHARACTER IN 

WRITE CONSOLE CHARACTER OUT 

WRITE LISTING CHARACTER OUT 

WRITE CHARACTER TO PUNCH DEVICE 

READ READER DEVICE 

MOVE TO TRACK 00 ON SELECTED DISK 

SELECT DISK DRIVE 

SET TRACK NUMBER 

SET SECTOR NUMBER 

SET DMA ADDRESS 

READ SELECTED SECTOR 

WRITE SELECTED SECTOR 

RETURN LIST STATUS 

SECTOR TRANSLATE SUBROUTINE 



Each jump address corresponds to a particular subroutine which performs 
the specific function, as outhned below. There are three major divisions in 
the jump table: the system (re)initiaUzation which results from calls on 
BOOT and WBOOT, simple character I/O performed by calls on CONST, 
CONIN, CONOUT, LIST, PUNCH, READER, and LISTST, and diskette 
I/O performed by calls on HOME, SELDSK, SETTRK, SETSEC, 
SETDMA, READ, WRITE, and SECTRAN. 

All simple character I/O operations are assumed to be performed in 
ASCII, upper and lower case, with high order (parity bit) set to zero. An 
end-of-file condition for an input device is given by an ASCII control-z 
( lAH). Peripheral devices are seen by CP/M as "logical** devices, and are 
assigned to physiced devices within the BIOS. 

In order to operate, the BDOS needs only the CONST, CONIN, and 
CONOUT subroutines (LIST, PUNCH, and READER may be used by 
PIP, but not the BDOS). Further, the LISTST entry is used currently 
only by DESPOOL, and thus, the initial version of CBIOS may have 
empty subroutines for the remaining ASCII devices. 
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The characteristics of each device are 

CONSOLE The principal interactive console which communicates with 
the operator, accessed through CONST, CONIN, and 
CONOUT. Typically, the CONSOLE is a device such as a 
CRT or Teletype. 

LIST The principal listing device, if it exists on your system, 

which is usually a hard-copy device, such as a printer or 
Teletype, 

PUNCH The principal tape punching device, if it exists, which is 

normally a high-speed paper tape punch or Teletype. 

READER The principal tape reading device, such as a simple optical 
reader or Teletype. 

Note that a single peripheral can be assigned as the LIST, 
PUNCH, and READER device simidtaneously. If no 
peripheral device is assigned as the LIST, PUNCH, or 
READER device, the CBIOS created by the user may give 
an appropriate error message so that the system does not 
"hang" if the device is accessed by PIP or some other user 
program. Alternately, the PUNCH and LIST routines can 
just simply return, and the READER routine can return 
with a lAH (ctl-Z) in reg A to indicate immediate end-of- 
file. 

For added flexibility, the user can optionally implement the 
"lOBYTE" function which allows reassignment of physical 
and logical devices. The lOBYTE function creates a 
mapping of logical to physical devices which can be altered 
during CP/M processing (see the STAT command). The 
definition of the lOBYTE function corresponds to the Intel 
standard as follows: a single location in memory (currently 
location 0003H) is maintained, called lOBYTE, which 
defines the logical to physical device mapping which is in 
effect at a particular time. The mapping is performed by 
splitting the lOBYTE into four distinct fields of two bits 
each, called the CONSOLE, READER, PUNCH, and LIST 
fields, as shown below: 

most significant least significant 

lOBYTE AT 0003H | LIST | PUNCH | READER I CONSOLE | 

bits 6,7 bits 4,5 bits 2,3 bits 0,1 
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The value in each field can be in the range 0-3, defining the 
assigned source or destination of each logical device. The 
values which can be assigned to each field are given below 

CONSOLE field (bits 0.1) 

— console is assigned to the console printer device (TTY:) 

1 — console is assigned to the CRT device (CRT:) 

2 — batch mode: use the READER as the CONSOLE input, 

and the LIST device as the CONSOLE output (BAT:) 

3 — user defined console device (UCl:) 

READER field (bits 2,3) 

- READER is the Teletype device (TTY:) 

2 — READER is the high-speed reader device (RDR:) 

2 — user defined reader # 1 (URl:) 

3 — user defined reader # 2 (UR2:) 

PUNCH field (bits 4,5) 

- PUNCH is the Teletype device (TTY:) 

1 — PUNCH is the high speed punch device (PUN:) 

2 — user defined punch # 1(UP1:) 

3 — user defined punch # 2 (UP2:) 

LIST field (bits 6,7) 

— LIST is the Teletype device (TTY:) 

1 — LIST is the CRT device (CRT:) 

2 — LIST is the line printer device (LPT:) 

3 — user defined list device (ULl:) 

Note again that the implementation of the lOBYTE is 
optional, and affects only the organization of your CHIOS. 
No CP/M systems use the lOBYTE (although they tolerate 
the existence of the lOB YTE at location 0003H ), except for 
PIP which allows access to the physical devices, and STAT 
which allows logical-physical assignments to be made 
and/or displayed (for more information, see the "CP/M 
Features and Facilities Guide"). In any case, the lOBYTE 
implementation should be omitted until your basic CBIOS 
is fully implemented and tested; then add the lOBYTE to 
increase your facilities. 

Disk I/O is always performed through a sequence of calls 
on the various disk access subroutines which set up the 
disk number to access, the track and sector on a particular 
disk, and the direct memory access ( DMA ) address involved 
in the I/O operation. After all these parameters have been 
set up, a call is made to the READ or WRITE function to 
perform the actual I/O operation. Note that there is often a 
single call to SELDSK to select a disk drive, followed by a 
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BOOT 



number of read or write operations to the selected disk 
before selecting anoither drive for subsequent operations. 
Similarly, there may be a single call to set the DMA 
address, followed by several calls which read or write from 
the selected DMA address before the DMA address is 
changed. The track and sector subroutines are always 
called before the READ or WRITE operations are 
performed. 

Note that the READ and WRITE routines should perform 
several retries (10 is standard) before reporting the error 
condition to the BDOS. If the error condition is returned to 
the BDOS, it will report the error to the user. The HOME 
subroutine may or may not actually perfon?n the track 00 
seek, depending upon your controller characteristics; the 
important point is that track 00 has been selected for the 
next operation, and is often treated in exactly the same 
manner as SETTRK with a parameter of 00. 

The exact responsibilities of each entry point subroutine 
are given below: 

The BOOT entry point gets control from the cold start 
loader and is responsible for basic system initialization, 
including sending a signon message (which can be omitted 
in the first version). If the lOBYTE function is im- 
plemented, it must be set at this point. The various system 
parameters which are set by the WBOOT entry point must 
be initialized, and control is transferred to the CCP at 
3400H+b for further processing. Note that reg C must be 
set to zero to select drive A. 



WBOOT The WBOOT entry point gets control when a warm start 

occurs. A warm start is performed whenever a user program 
branches to location OOOOH, or when the CPU is reset from 
the front panel. The CP/M system must be loaded from the 
first two tracks of drive A up to, but not including, the 
BIOS (or CBIOS, if you have completed your patch). 
System parameters must be initialized as shown below: 



location 0,1,2 
location 3 
location 5,6,7 



set to JMP WBOOT for warm 
starts (OOOOH: JMP 4A03H+b) 

set initial value of lOBYTE, if 
implemented in your CBIOS 

set to JMP BDOS, which is the 
primary entry point to CP/M for 
transient programs. (0005H: JMP 
3C06HH-b) 
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(see Section 9 for complete details of page zero use) Upon 
completion of the initialization, the WBOOT program must 
branch to the CCP at 3400H-l-b to (re)start the system. 
Upon entry to the CCP, register C is set to the drive to 
select after system initialization. 

CONST Sample the status of the currently assigned console device 

and return OFFH in register A if a character is ready to 
read, and OOH in register A if no console characters are 
ready. 

CONIN Read the next console character into register A, and set the 

parity bit (high order bit) to zero. If no console character is 
ready, wait until a character is t5T)ed before returning. 

CONOUT Send the character from register C to the console output 
device. The character is in ASCII, with high order parity 
bit set to zero. You may want to include a time-out on a line 
feed or carriage return, if your console device requires some 
time interval at the end of the Une (such as a TI Silent 700 
terminal). You can, if you wish, filter out control characters 
which cause your console device to react in a strange way (a 
control-z causes the Lear Seigler terminal to clear the 
screen, for example), 

LIST Send the character from register C to the currently assigned 

listing device. The character is in ASCII with zero parity. 

PUNCH Send the character from register C to the currently assigned 

punch device. The character is in ASCII with zero parity. 

READER Read the next character from the currently assigned reader 
device into register A with zero parity (high order bit must 
be zero), an end of file condition is reported by returning an 
ASCII control-z (lAH). 

HOME Return the disk head of the currently selected disk ( initially 

disk A) to the track 00 position. If your controller allows 
access to the track flag from the drive, step the head until 
the track flag is detected. If your controller does not 
support this feature, you can translate the HOME call into 
a call on SETTRK with a parameter of 0. 

SELDSK Select the disk drive given by register C for further 
operations, where register C contains for drive A, 1 for 
drive B, and so-forth up to 15 for drive P (the standard 
CP/M distribution version supports four drives). On each 
disk select, SELDSK must return in HL the base address of 
a 16-byte area, called the Disk Parameter Header, described 
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in the Section 10. For standard floppy disk drives, the 
contents of the header and associated tables does not 
change, and thus the program segment included in the 
sample CBIOS performs this operation automatically. If 
there is an attempt to selct a non-existent drive, SELDSK 
returns HL=OOOOH as an error indicator. Although 
SELDSK must return the header address on each call, it is 
advisable to postpone the actual physical disk select 
operation until an I/O function (seek, read or write) is 
actually performed, since disk selects often occur without 
ultimately performing any disk I/O, and many controllers 
will unload the head of the current disk before selecting the 
new drive. This would cause an excessive amount of noise 
and disk wear. 

SETTRK Register BC contains the track number for subsequent disk 
accesses on the currently selected drive. You can choose to 
seek the selected track at this time, or delay the seek until 
the next read or write actually occurs. Register BC can take 
on values in the range 0-76 corresponding to valid track 
numbers for standard floppy disk drives, and 0-65535 for 
non-standard disk subsystems. 

SETSEC Register BC contains the sector number ( 1 through 26) for 

subsequent disk accesses on the currently selected drive. 
You can choose to send this information to the controller at 
this point, or instead delay sector selection until a read or 
write operation occurs. 

SETDMA Register BC contains the DMA (disk memory access) 
address for subsequent read or write operations. For 
example, if B = OOH and C = 80H when SETDMA is 
called, then all subsequent read operatons read their data 
into 80H through OFFH, and all subsequent write 
operations get their data from 80H through OFFH, until 
the next call to SETDMA occurs. The initial DMA address 
is assumed to be 80H. Note that the controller need not 
actually support direct memory access. If, for example, all 
data is received and sent through I/O ports, the CBIOS 
which you construct will use the 128 byte area starting at 
the selected DMA address for the memory buffer during 
the following read or write operations. 

READ Assuming the drive has been selected, the track has been 

set, the sector has been set, and the DMA address has been 
specified, the READ subroutine attempts to read one 
sector based upon these parameters, and returns the 
following error codes in register A: 
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1 



no errors occurred 

non-recoverable error condition occurred 



Currently, CP/M responds only to a zero or non-zero value 
as the return code. That is, if the value in register A is 
then CP/M assumes that the disk operation completed 
properly. If an error occurs, however, the CBIOS should 
attempt at least 10 retries to see if the error is recoverable. 
When an error is reported the BDOS will print the message 
"BDOS ERR ON x: BAD SECTOR". The operator then 
has the option of typing <cr> to ignore the error, or ctl-C 
to abort. 

WRITE Write the data from the currently selected DMA address to 

the currently selected drive, track, and sector. The data 
should be marked as "non deleted data" to maintain 
compatibility with other CP/M systems. The error codes 
given in the READ command are returned in register A, 
with error recovery attempts as described above. 

LISTST Return the ready status of the list device. Used by the 

DESPOOL program to improve console response during its 
operation. The value 00 is returned in A if the list device is 
not ready to accept a character, and OFFH if a character can 
be sent to the printer. Note that a 00 value always suffices. 

SECTRAN Performs sector logical to physical sector translation in 
order to improve the overall response of CP/M. Standard 
CP/M systems are shipped with a "skew factor" of 6, where 
six physical sectors are skipped between each logical read 
operation. This skew factor allows enough time between 
sectors for most programs to load their buffers without 
missing the next sector. In particular computer systems 
which use fast processors, memory, and disk subsystems, 
the skew factor may be changed to improve overall response. 
Note, however, that you should maintain a single density 
IBM compatible version of CP/M for information transfer 
into and out of your computer system, using a skew factor 
of 6. In general, SECTRAN receives a logical sector number 
in BC, and a translate table address in DE. The sector 
number is used as an index into the translate table, with the 
resulting physical sector number in HL. For standard 
systems, the tables and indexing code is provided in the 
CBIOS and need not be changed. 
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A Sample BIOS 

The program shown in Appendix C can serve as a basis for your first 
BIOS. The simplest functions are assumed in this BIOS, so that you can 
enter it through the front panel, if absolutely necessary. Note that the user 
must alter and insert code into the subroutines for CONST, CONIN, 
CONOUT, READ, WRITE, and WAITIO subroutines. Storage is reserved 
for user-supplied code in these regions. The scratch area reserved in page 
zero (see Section 9) for the BIOS is used in this program, so that it could be 
implemented in ROM, if desired. 

Once operational, this skeletal version can be enhanced to print the initial 
sign-on message and perform better error recovery. The subroutines for 
LIST, PUNCH, and READER can be filled-out, and the lOBYTE function 
can be implemented. 

A Sample Cold Start Loader 

The program shown in Appendix D can serve as a basis for your cold start 
loader. The disk read function must be supplied by the user, and the 
program must be loaded somehow starting at location 0000. Note that 
space is reserved for your patch so that the total amount of storage 
required for the cold start loader is 128 bytes. Eventually, you will 
probably want to get this loader onto the first disk sector (track 0, sector 
1), and cause your controller to load it into memory automatically upon 
system start-up. Alternatively, you may wish to place the cold start loader 
into ROM, and place it above the CP/M system. In this case, it will be 
necessary to originate the program at a higher address, and key-in a jump 
instruction at system start-up which branches to the loader. Subsequent 
warm starts will not require this key-in operation, since the entry point 
'WBOOT' gets control, thus bringing the system in from disk 
automatically. Note also that the skeletal cold start loader has minimal 
error recovery, which may be enhanced on later versions. 

Reserved Locations in Page Zero 

Main memory page zero, between locations OOH and OFFH, contains 
several segments of code and data which are used during CP/M processing. 
The code and data areas are given below for reference purposes. 

Locations Contents 

from to 

OOOH — 0002H Contains a jump instruction to the warm start entry 

point at location 4A03H+b. This allows a simple 
programmed rest€ut ( JMP OOOOH) or manual restart 
from the front panel. 
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0003H - 0003H 



Contains the Intel standard lOBYTE, which is 
optionally included in the user's CBIOS, as described 
in Section 6. 



0004H — 0004H Current default drive number (0= A, . . , ,15=P). 



0005H - 0007H 



0008H - 0027H 
0030H - 0037H 
0038H - 003AH 



003BH - 003FH 
0040H - 004FH 



0050H - 005BH 
005CH - 007CH 

007DH - 007FH 
0080H - OOFFH 



Contains a jump instruction to the BDOS, and 
serves two purposes: JMP 0005H provides the 
primary entry point to the BDOS, as described in 
the manual "CP/M Interface Guide," and LHLD 
0006H brings the address field of the instruction to 
the HL register pair. This value is the lowest address 
in memory used by CP/M (assuming the CCP is 
being overlayed). Note that the DDT program will 
change the address field to reflect the reduced 
memory size in debug mode. 

(interrupt locations 1 through 5 not used) 

(interrupt location 6, not currently used — reserved) 

Restart 7 — Contains a jump instruction into the 
DDT or SID program when running in debug mode 
for programmed breakpoints, but is not otherwise 
used by CP/M. 

(not currently used — reserved) 

16 byte area reserved for scratch by CBIOS, but is 
not used for any purpose in the distribution version 
not used for any purpose in the distribution version 
of CP/M 

(not currently used — reserved) 

default file control block produced for a transient 
program by the Console Command Processor. 

Optional default random record position 

default 128 byte disk buffer (also filled with the 
command line when a transient is loaded under the 
CCP). 



Note that this information is set-up for normal operation under the CP/M 
system, but can be overwritten by a transient program if the BDOS 
facilities are not required by the transient. 

If, for example, a particular program performs only simply I/O and must 
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begin execution at location 0, it can be first loaded into the TPA, using 
normal CP/M facilities, with a small memory move program which gets 
control when loaded (the memory move program must be control from 
location OlOOH, which is the assumed beginning of all transient progreuns). 
The move program can then proceed to move the entire memory image 
down to location 0, and pass control to the starting address of the memory 
load. Note that if the BIOS is overwritten, or if location (containing the 
warm start entry point) is overwritten, the the programmer must bring 
the CP/M system back into memory with a cold start sequence. 



Disk Parameter Tables 

Tables are included in the BIOS which describe the particular 
characteristics of the disk subsystem used with CP/M. These tables can 
be either hand-coded, as shown in the sample CBIOS in Appendix C, or 
automatically generated using the DISKDEF macro library, as shown in 
Appendix B. The purpose here is to describe the elements of these tables. 

In general, each disk drive has an associated (16-byte) disk parameter 
header which both contains information about the disk drive and provides 
a scratchpad area for certain BDOS operations. The format of the disk 
parameter header for each drive is shown below 

Disk Parameter Header 

I XLT I 0000 I 0000 I 0000 |DIRBUF| DPB | CSV | ALV | 

16b 16b 16b 16b 16b 16b 16b 16b 

where each element is a word (16-bit) value. The meaning of each Disk 
Parameter Header (DPH) element is 

XLT Address of the logical to physical translation vector, if used 

for this particular drive, or the value OOOOH if no sector 
translation takes place (i.e., the physical and logical sector 
numbers are the same). Disk drives with identical sector 
skew factors share the same translate tables. 

0000 Scratchpad values for use within the BDOS (initial value is 

unimportant). 

DIRBUF Address of a 128 byte scratchpad area for directory 
operations within BDOS. All DPH's address the same 
scratchpad area. 

DPB Address of a disk parameter block for. this drive. Drives 

with identical disk characteristics address the same disk 
parameter block. 
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CSV 



ALV 



Address of a scratchpad area used for software check for 
changed disks. This address is different for each DPH. 

Address of a scratchpad area used by the BDOS to keep 
disk storage allocation information. This address is different 
for each DPH. 



Given n disk drives, the DPH's are arranged in a table whose first row of 16 
bytes corresponds to drive 0, with the last row corresponding to drive 
n— 1. The table thus appears as 

DPBASE: 

00 I XLT 00 I 0000 I 0000 | 0000 | DIRBUF | DBP 00 | CSV 00 | ALV 00 | 

01 I XLT 01 I 0000 I 0000 | 0000 | DIRBUF | DBP 01 | CSV 01 | ALV 01 | 

(and so-forth through) 
n- 1 1 XLTn- 1 1 0000 | 0000 | 0000 | DIRBUF | DBPn- 1 | CSVn- 1 | ALVn- 1 | 



where the label DBASE defines the base address of the DPH table. 

A responsibility of the SELDSK subroutine is to return the base address 
of the DPH for the selected drive. The following sequence of operations 
returns the table address, with a OOOOH returned if the selected drive does 
not exist. 



NDISKS EQU 
NDISKS EQU 



;NUMBER OF DISK DRIVES 



SELDSK: 






;SELECT DISK GIVEN BY BC 


LXI 


H.OOOH 


;ERROR CODE 


MOV 


A,C 


;DRIVE OK? 


CPI 


NDISKS 


;CY IF SO 


RNC 




;RET IF ERROR 


;N0 ERROR, CONTINUE 


MOV 


L,C 


;LOW(DISK) 


MOV 


H,B 


;HIGH (DISK) 


DAD 


H 


;*2 


DAD 


H 


;*4 


DAD 


H 


;*8 


DAD 


H 


;*16 


LXI 


D,DPBASE 


;FIRST DPH 


DAD 


D 


;DPH (DISK) 


RET 
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The translation vectors (XLT 00 through XLTn- 1 ) are located elsewhere 
in the BIOS, and simply correspond one-for-one with the logical sector 
niunbers zero through the sector count— 1. The Disk Parameter Block 
(DPB) for each drive is more complex. A particular DPB, which is 
addressed by one or more DPH's, takes the general form 



SPT I BSH |BLM|EXM | DSM | DRM | ALO | ALl | CKS | 0FF| 
16b 8b 8b 8b 16b 16b 8b 8b 16b 16b 



where each is a byte or word value, as shown by the "8b" or "16b" indicator 
below the field. 

SPT is the total number of sectors per track 

BSH is the data allocation block shift factor, determined by the 

data block allocation size. 

EXM is the extent mask, determined by the data block allocation 

size and the number of disk blocks. 

DSM determines the total storage capacity of the disk drive 

DRM determines the total number of directory entries which can 

be stored on this drive AL0,AL1 determine reserved 
directory blocks. 

CKS is the size of the directory check vector 

OFF is the nimaber of reserved tracks at the beginning of the 

(logical) disk. 

The values of BSH and BLM determine (implicitly) the data Uocation size 
BLS, which is not an entry in the disk parameter block. Given that the 
designer has selected a value for BLS, the values of BSH and BLM are 
shown in the table below 



BLS 


BSH 


BLM 


1,024 


3 


7 


2,048 


4 


15 


4,096 


5 


31 


8,192 


6 


63 


16,384 


7 


127 



where all values are in decimal. The value of EXM depends upon both the 
BLS and whether the DSM veilue is less than 256 or greater than 255, as 
shown in the following table 
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BLS DSM < 256 DSM > 255 
1,024 N/A 

2,048 1 

4,096 3 1 

8,192 7 3 

16,384 15 7 

The value of DSM is the maximum data block number supported by this 
particular drive, measured in BLS units. The product BLS times (DSM+ 1 ) 
is the total number of bytes held by the drive and, of course, must be 
within the capacity of the physical disk, not counting the reserved 
operating system tracks. 

The DRM entry is the one less than the total number of directory entries, 
which can take on a 16-bit value. The values of ALl and ALl, however, are 
determined by DRM. The two values ALO and ALl can together be 
considered a string of 16-bits, as shown below. 



I ALO I ALl I 

LiJlLiJli"LlJliT 

00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 

where position 00 corresponds to the high order bit of the byte labelled 
AlO, and 15 corresponds to the low order bit of the byte labelled ALl. Each 
bit position reserves a data block for number of directory entries, thus 
allowing a total of 16 data blocks to be assigned for directory entries (bits 
are assigned starting at 00 and filled to the right until position 15). Each 
directory entry occupies 32 bytes, resulting in the following table 



BLS 


Directory Entries 


1,024 


32 times # bits 


2,048 


64 times # bits 


4,096 


128 times # bits 


8,192 


256 times # bits 


16,384 


512 times # bits 



Thus, if DRM = 127 ( 128 director entries), and BLS = 1024, then there are 
32 directory entries per block, requiring 4 reserved blocks. In this case, the 
4 high order bits of ALO are set, resulting in the values ALO = OFOH and 
ALl = OOH. 

The CKS value is determined as follows: if the disk drive media is 
removable, then CKS = (DRM + l)/4, where DRM is the last directory 
entry number. If the media is fixed, then set CKS = (no directory records 
are checked in this case). 
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Finally, the OFF field determines the number of tracks which are skipped 
at the beginning of the physical disk. This value is automatically added 
whenever SETTRK is called, and can be used as a mechanism for skipping 
reserved operating system tracks, or for partitioning a large disk into 
smaller segmented sections. 

To complete the discussion of the DPB, recall that several DPH's can 
address the same DPB if their drive characteristics are identical. Further, 
the DPB can be dynamically changed when a new drive is addressed by 
simply changing the pointer in the DPH since the BDOS copies the DPB 
values to a local area whenever the SELDSK function is invoked. 

Returning back to the DPH for a particular drive, note that the two 
address values CSV and ALV remain. Both addresses reference an area of 
uninitialized memory following the BIOS. The areas must be unique for 
each drive, and the size of each area is determined by the values in the 
DPB. 

The size of the area addressed by CSV is CKS bytes, which is sufficient to 
hold the directory check information for this particular drive. If CKS = 
(DRM+l)/4, then you must reserve (DRM + l)/4 bytes for directory 
check use. If CKS = 0, then no storage is reserved. 

The size of the area addressed by ALV is determined by the maximum 
number of data blocks allowed for this particular disk, and is computed as 
(DSM/8)+l. 

The CBIOS shown in Appendix C demonstrates an instance of these 
tables for standard 8" single density drives. It may be useful to examine 
this program, and compare the tabular values with the definitions given 
above. 



The DISKDEF Macro Library 

A macro library is shown in Appendix F, called DISKDEF, which greatly 
simplifies the table construction process. You must have access to the 
MAC macro assembler, of course, to use the DISKDEF facility, while the 
macro library is included with all CP/M 2.0 distribution disks. 

A BIOS disk definition consists of the following sequence of macro 
statements: 
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MACLIB 


DISKDEF 


DISKS 

DISKDEF 

DISKDEF 


n 

0,... 

1,... 


DISKDEF 


n-1 



ENDEF 



where the MACLIB statement loads the DISKDEF.LIB file (on the same 
disk as your BIOS) into MAC'S internal tables. The DISKS macro call 
follows, which specifies the number of drives to be configured with your 
system, where n is an integer in the range 1 to 16. A series of DISKDEF 
macro calls then follow which define the characteristics of each logical 
disk, through n- 1 (corresponding to logical drives A through P). Note 
that the DISKS and DISKDEF macros generate the in-line fixed data 
tables described in the previous section, and thus must be placed in a non- 
executable portion of your BIOS, typically directly following the BIOS 
jump vector. 

The remaining portion of your BIOS is defined following the DISKDEF 
macros, with the ENDEF macro call immediately preceding the END 
statement. The ENDEF (End of Diskdef ) macro generates the necessary 
uninitialized RAM areas which are located in memory above your BIOS. 

The form of the DISKDEF macro call is 

DISKDEF dn,fsc,lsc,[skf],bls,dks,dir,cks,ofs,[01 
where 

dn is the logical disk number, to n- 1 

fsc is the first physical sector number (0 or 1 ) 

Isc is the last sector number 

skf is the optional sector skew factor 

bis is the data allocation block size 

dir is the number of directory entries 

cks is the number of "checked" directory entries 

ofs is the track offset to logical track 00 

[0] is an optional 1.4 compatibility flag 

The value "dn" is the drive number being defined with this DISKDEF 
macro invocation. The "fsc" parameter accounts for differing sector 
numbering systems, and is usually or 1. The "Isc" is the last numbered 
sector on a track. When present, the "skf" parameter defines the sector 
skew.factor which is used to create a sector translation table according to 
the skew. If the nxzmber of sectors is less than 256, a single-byte table is 
created, otherwise each translation table element occupies two bytes. No 
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translation table is created if the skf parameter is omitted (or equal to 0). 
The "bis" parameter specifies the nximber of bytes allocated to each data 
block, and takes on the values 1024, 2048, 4096,8192, or 16384. Generally, 
performance increases with larger data block sizes since there are fewer 
directory references and logically connected data records are physically 
close on the disk. Further, each directory entry addresses more data and 
the BIOS-resident ram space is reduced. The "dks" specifies the total disk 
size in "bis" units. That is, if the bis = 2048 and dks = 1000, then the total 
disk capacity is 2,048,000 bytes. If dks is greater than 255, then the block 
size parameter bis must be greater than 1024. The value of "dir" is the total 
number of directory entries which may exceed 255, if desired. The "cks" 
parameter determines the number of directory items to check on each 
directory scan, and is used internally to detect changed disks during 
system operation, where an intervening cold or warm start has not 
occurred (when this situation is detected, CP/M automatically marks the 
disk read/only so that data is not subsequently destroyed). As stated in 
the previous section, the value of cks = dir when the media is easily 
changed, as is the case with a floppy disk subsystem. If the disk is 
permanently mounted, then the value of cks is typically 0, since the 
probability of changing disks without a restart is quite low. The "ofs" 
value determines the number of tracks to skip when this particular drive is 
addressed, which can be used to reserve additional operating system space 
or to simulate several logical drives on a single large capacity physical 
drive. Finally, the [0] parameter is included when file compatibility is 
required with versions of 1.4 which have been modified for higher density 
disks. This parameter ensures that only 16K is allocated for each directory 
record, as was the case for previous versions. Normally, this parameter is 
not included. 

For convenience and economy of table space, the special form 

DISKDEF i,j 

gives disk i the same characteristics as a previously defined drive j. A 
standard four-drive single density system, which is compatible with 
version 1.4, is defined using the following macro invocations: 



DISKS 


4 


DISKDEF 


0,1.26,6,1024,243,64,64,2 


DISKDEF 


1,0 


DISKDEF 


2,0 


DISKDEF 


3,0 



ENDEF 

with all disks having the same parameter values of 26 sectors per track 
(numbered 1 through 26), with 6 sectors skipped between each access, 
1024 bytes per data block, 243 data blocks for a total of 243k byte disk 
capacity, 64 checked directory entries, and two operating system tracks. 
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DPBASE 


EQU 


DPEO: 


DW 


DPEl: 


DW 


DPE2: 


DW 


DPE3: 


DW 



The DISKS macro generates n Disk Parameter Headers (DPH's), starting 
at the DPH table address DPBASE generated by the macro. Each disk 
header block contains sixteen bytes, as described above, and correspond 
one-for-one to each of the defined drives. In the four drive standard 
system, for example, the DISKS macro generates a table of the form: 

$ 

XLTO,OO0OH,O0OOH,0000H,DIRBUF,DPBO»CSVO,ALVO 
XLTO,OOOOH,OOOOH,OOOOH,DIRBUF.DPBO,CSV1,ALV1 
XLTO,0O00H,0000H,O000H.DIRBUF,DPB0,CSV2,ALV2 
XLTO,0O00H,00O0H,0OO0H,DIRBUF.DPBO,CSV3,ALV3 

where the DPH labels are included for reference purposes to show the 
beginning table addresses for each drive through 3. The values contained 
within the disk parameter header are described in detail in the previous 
section. The check and allocation vector addresses are generated by the 
ENDEF macro in the ram area following the BIOS code and tables. 

Note that if the "skf" (skew factor) parameter is omitted (or equal to 0), the 
translation table is omitted, and a OOOOH value is inserted in the XLT 
position of the disk parameter header for the disk. In a subsequent call to 
perform the logical to physical translation, SECTRAN receives a 
translation table address of DE = OOOOH, and simply returns the original 
logical sector from BC in the HL register pair. A translate table is 
constructed when the skf parameter is present, and the (non-zero) table 
address is placed into the corresponding DPH*s. The table shown below, 
for example, is constructed when the standard skew factor skf = 6 is 
specified in the DISKDEF macro call: 

XLTO: DB 1,7,13,19,25,5,11,17,23,3,9,15,21 
DB 2,8,14,20,26,6,12,18,24,4,10,16,22 

Following the ENDEF macro call, a number of uninitialized data areas are 
defined. These data areas need not be a part of the BIOS which is loaded 
upon cold start, but must be available between the BIOS and the end of 
memory. The size of the uninitialized RAM area is determined by EQU 
statements generated by the ENDEF macro. For a standard four-drive 
system, the ENDEF macro might produce 

4C72 = BEGDAT EQU $ 

(data areas) 
4DB0 = ENDDAT EQU $ 

013C = DATSIZ EQU $- BEGDAT 

which indicates that uninitialized RAM begins at location 4C72H, ends at 
4DB0H-1, and occupies 013CH bytes. You must ensure that these 
addresses are free for use after the system is loaded. 

After modification, you can use the STAT program to check your drive 
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characteristics, since STAT uses the disk parameter block to decode the 
drive information. The STAT command form 

STATd:DSK: 

decodes the disk parameter block for drive d (d = A, . . . ,P ) and displays the 
values shown below: 

r: 128 Byte Record Capacity 

k: Kilobyte Drive Capacity 

d: 32 Byte Directory Entries 

c: Checked Directory Entries 

e: Records/ Extent 

b: Records/ Block 

s: Sectors/ Track 

t: Reserved Tracks 

Three examples of DISKDEF macro invocations are shown below with 
corresponding STAT parameter values (the last produces a full 8-megabyte 
system). 

DISKDEF 0,1,58„2048,256,128,128,2 
r=4096, k=512, d=128, c=128, e=256, b=16, s=58, t=2 

DISKDEF 0,1,58„2048,1024,300,0,2 
r=16384, k=2048, d=300, c=0, e=128, b=16, s=58, t=2 

DISKDEF 0,1,58„16384,512,128,128,2 
r=65536, k=8192, d=128, c=128, e=1024, b=128, s=58, t=2 



Sector Blocking and Deblocking 

Upon each call to the BIOS WRITE entry point, the CP/M BDOS 
includes information which allows effective sector blocking and deblocking 
where the host disk subsystem has a sector size which is a multiple of the 
basic 128-byte unit. The purpose here is to present a general-purpose 
algorithm which can be included within your BIOS which uses the BDOS 
information to perform the operations automatically. 

Upon each call to WRITE, the BDOS provides the following information 
in register C: 

= normal sector write 

1 = write to directory sector 

2 = write to the first sector 

of a new data block 
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Condition occurs whenever the next write operation is into a previously 
written area, such as a random mode record update, when the write is to 
other than the first sector of an unallocated block, or when the write is not 
into the directory area. Condition 1 occurs when a write into the directory 
area is performed. Condition 2 occurs when the first record (only) of a 
newly allocated data block is written. In most cases, application programs 
read or write multiple 128 Cyte sectors in sequence, and thus there is little 
overhead involved in either operation when blocking and deblocking 
records since pre-read operations can be avoided when writing records. 

Appendix G lists the blocking and deblocking algorithms in skeletal form 
(this file is included on your CP/M disk). Generally, the algorithms map 
all CP/M sector read operations onto the host disk through an intermediate 
buffer which is the size of the host disk sector. Throughout the program, 
values and variables which relate to the CP/M sector involved in a seek 
operation are prefixed by "sek", while those related to the host disk system 
are prefixed by "hst." The equate statements beginning on line 29 of 
Appendix G define the mapping between CP/M and the host system, and 
must be changed if other than the sample host system is involved. 

The entry points BOOT and WBOOT must contain the initialization code 
starting on line 57, while the SELDSK entry point must be augmented by 
the code starting on line 65. Note that although the SELDSK entry point 
computes and returns the Disk Parameter Header address, it does not 
physically select the host disk at this point (it is selected later at 
READHST or WRITEHST). Further, SETTRK, SETSEC, and SETDMA 
simply store the values, but do not take any other action at this point. 
SECTRAN performs a trivial function of returning the physical sector 
number. 

The principal entry points are READ and WRITE, starting on lines 110 
and 125, respectively. These subroutines take the place of your previous 
READ and WRITE operations. 

The actual physical read or write takes place at either WRITEHST or 
READHST, where all values have been prepared: hstdsk is the host disk 
number, hsttrk is the host track number, and hstsec is the host sector 
number (which may require translation to a physical sector number). You 
must insert code at this point which performs the full host sector read or 
write into, or out of, the buffer at hstbuf of length hstsiz. All other 
mapping functions are performed by the algorithms. 

This particular algorithm was tested using an 80 megabyte hard disk unit 
which was originally configured for 128 byte sectors, producing 
approximately 35 megabytes of formatted storage. When configured for 
512 byte host sectors, usable storage increased to 57 megabytes, with a 
corresponding 400% improvement in overall response. In this situation, 
there is no apparent overhead involved in deblocking sectors, with the 
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advantage that user programs still maintain the (less memory consuming) 
128-b3rte sectors. This is primarily due, of course, to the information 
provided by the BDOS which eliminates the necessity for pre-read 
operations to take place. 
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APPENDIX A: THE MDS COLD START LOADER 



0000 r= 
ffff = 
0000 = 



0000 = 

0000 = 
0806 = 
1880 = 
1600 = 
1603 = 

3000 

1880 = 

0002 = 
0031 = 
0019 = 
0018 = 

f800 = 
ff0f = 

0078 = 

0079 = 
007b = 
007f = 

0078 = 

0079 = 
007a = 
00ff = 

0003 = 

0004 = 
0100 = 



3000 310001 

3003 db79 
3005 db7b 



3007 dbff 



MDS-800 Cold Start Loader for CP/M 2.0 
Version 2,0 August, 1979 



false 

true 

testing 

bias 

bias 

cpmb 

bdos 

bdose 

boot 

rboot 



bdosl 
ntrks 
bdoss 
bdos0 
bdosl 

Tnond0 

rinon80 

base 

rtype 

rbyte 

reset 

dstat 

ilow 

ihigh 

bsw 

recal 

readf 

stack 

? 

rstart: 



equ 
equ 
equ 

if 

equ 

endif 

if 

equ 

endif 

equ 

equ 

equ 

equ 

equ 

org 

equ 
equ 
equ 
equ 
ecu 

equ 
equ 
equ 
equ 
equ 
equ 

equ 
equ 
equ 
equ 
equ 
equ 
equ 



not false 
false 

testing 
03400h 

not testing 
0000h 

bias 

806h+bias 

1880h+bias 

1600h+bias 

boot+3 



;base of dos load 

; entry to dos for calls 

;end of dos load 

;cold start entry point 

;warm start entry point 



3000h 



; loaded here by hardware 



bdose-cpmb 

2 

bdosl/128 

25 

bdoss-bdos0 



tracks to read 

# sectors in bdos 

# on track 

# on track 1 



0f800h ; Intel monitor base 

0ff0fh ; restart location for mon80 

078h ;*base* used by controller 

base+1 ; result type 

base+3 ; result byte 

base+7 ;reset controller 

base ;disk status port 

base+1 ;low iopb address 

base+2 ;high iopb address 

0ffh ;boot switch 

3h ;recalibrate selected drive 

4h ;disk read function 

100h ;use end of boot for stack 



Ixi 
; clear 

in 

in 
; check 
coldstart: 

in 

fni 
nz 



sp, stack; in case of call to mon80 
disk status 

rtype 

rbyte 
if boot switch is off 

bsw 



177 



300e d37f 



clear the controller 

out reset ;logic cleared 



3010 0602 
3012 214230 



irivi b.ntrks ;nuinber of tracks to read 
Ixi hriopb0 



start: 



3015 7d 

3016 d379 

3018 7c 

3019 d37a 
301b db78 



3022 db79 
3024 e603 
3026 fe02 



wait0 ; 



3028 d20030 



302b db7b 

302d 17 
302e dc0fff 

3031 If 

3032 e61e 



3034 C20030 



read first/next track into cpmb 



mov 


a,l 


out 


ilow 


mov 


a^h 


out 


ihigh 


in 


dstat 


ani 


4 •,.« 


Dz 


wait0 



check disk status 

in rtype 

ani lib 

cpi 2 



if 

cnc 

endif 

if 

jnc 

endif 



testing 

rinon80 ?go to monitor if 11 or 10 

not testing 

rstart ; retry the load 



in rbyte ? i/o complete, check status 

if not ready, then go to mon80 

ral 

cc rmon80 ;not ready bit set 

rar ;restore 

ani 11110b ;overrun/addr err/seek/crc 



if 

cnz 

endif 

if 

jnz 

endif 



testing 

rmon80 ;go to monitor 

not testing 

rstart ; retry the load 



3037 110700 

303a 19 

303b 05 

303c C21530 



Ixi d^iopbl ; length of iopb 

dad d ; addressing next iopb 

dcr b ; count down tracks 

jnz start 



303f C30016 



jmp boot, print message, set-up jmps 
jmp boot 

parameter blocks 
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3042 80 


iopb0; 


db 


80h 


;iocw, no update 


3043 04 




db 


readf 


;read function 


3044 19 




db 


bdos0 


;# sectors to read trk 


3045 00 




db 





; track 


3046 02 




db 


2 


;start with sector 2, trk 


3047 0000 




dw 


cpmb 


; start at base of bdos 


0007 = 


iopbl 


equ 


$-iopb0 




3049 80 


iopbl : 


db 


80h 




304a 04 




db 


readf 




304b 18 




db 


bdosl 


;sectors to read on track 1 


304c 01 




db 


1 


; track 1 


304d 01 




db 


1 


; sector 1 


304e 800c 




dw 


cpmb+bdi 


030*128 jbase of second rd 



3050 end 
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APPENDIX B: THE MDS BASIC I/O SYSTEM (BIOS) 



0014 = 



vers 



4a00 
3400 
3c06 
1600 
002c 
0002 
0004 
0080 
000a 



cpnib 

bdos 

cpml 

nsects 

offset 

cdisk 

buff 

retry 



4a00 c3b34a 

4a03 c3c34a wboote: 

4a06 c3614b 

4a09 c3644b 

4a0c c36a4b 



mds-800 i/o drivers for cp/m 2.0 
(four drive single density version) 

version 2.0 august, 1979 

equ 20 ;version 2.0 

copyright (c) 1979 
digital research 
box 579, pacific grove 
California, 93950 



org 
egu 
equ 
equ 
equ 
equ 
equ 
equ 
equ 

perfo 

boot 

wboot 

(boot 

const 



4a00h 

3400h 

3c06h 

$-cpmb 

cpml/128 

2 

0004h 

0080h 

10 



base of bios in 20k system 

base of cpm ccp 

base of bdos in 20k system 

length (in bytes) of cpm system 

number of sectors to load 

number of disk tracks used by cp 

address of last logged disk 

default buffer address 

max retries on disk i/o before e 



rm following functions 

cold start 

warm start (save i/o byte) 
and wboot are the same for mds) 

console status 

reg-a = 00 if no character ready 

reg-a = ff if character ready 
conin console character in (result in reg-a) 
conout console character out (char in reg-c) 
list list out (char in reg-c) 
punch punch out (char in reg-c) 
reader paper tape reader in (result to reg-a) 
home move to track 00 

(the following calls set-up the io parameter bloc 
mds, which is used to perform subsequent reads an 
seldsk select disk given by reg-c (0,1,2,..) 
settrk set track address (0,...76) for sub r/w 
setsec set sector address (1,...,26) 
setdma set subsequent dma address (initially 80h 

read/write assume previous calls to set i/o parms 
read read track/sector to preset dma address 
write write track/sector from preset dma addres 

jump vector for indiviual routines 

jmp boot 

jmp wboot 

jmp const 

jmp conin 

jmp conout 
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4a0f 


c36d4b 


4al2 


c3724b 


4al5 


c3754b 


4al8 


c3784b 


4alb 


c37d4b 


4ale 


c3a74b 


4a21 


c3ac4b 


4a24 


c3bb4b 


4a27 


c3cl4b 


4a2a 


c3ca4b 


4a2d 


c3704b 


4a30 


c3bl4b 



4a33+= dpbase 

4a33+824a00 dpe0: 

4a37+000000 

4a3b+6e4c73 

4a3f+0d4dee 

4a43+824a00 dpel: 

4a47+000000 

4a4b+6e4c73 

4a4f+3c4dld 

4a53+824a00 dpe2: 

4a57+000000 

4a5b+6e4c73 

4a5f+6b4d4c 

4a63+824a00 dpe3 : 

4a67+000000 

4a6b+6e4c73 

4a6f+9a4d7b 



4a73+= 

4a73+la00 

4a75+03 

4a76+07 

4a77+00 

4a78+f200 

4a7a+3f00 

4a7c+c0 

4a7d+00 

4a7e+1000 

4a80+0200 

4a82+ = 

4a82+01 

4a83+07 

4a84+0d 

4a85+13 

4a86+19 

4a87+05 

4a88+0b 

4a89+ll 

4a8a+17 

4a8b+03 



dpb0 



xlt0 



jmp 


list 




jmp 


punch 




jmp 


reader 




jmp 


home 




jmp 


seldsk 




jmp 


settrk 




jmp 


setsec 




jmp 


setdma 




jmp 


read 




jmp 


write 




jmp 


listst ;list 


status 


jmp 


sectran 




maclib 


diskdef ;load 


the disk definition library 


disks 


4 ;four 


disks 


equ 


$ ;base 


of disk parameter blocks 


dw 


xlt0,0000h 


; translate table 


dw 


0000h,0000h 


;scratch area 


dw 


dirbuf ,dpb0 


;dir buff,parm block 


dw 


CSV0 ,alv0 


;check, alloc vectors 


dw 


xltl,0000h 


; translate table 


dw 


0000h,0000h 


;scratch area 


dw 


dirbuf rdpbl 


;dir buff,parm block 


dw 


csvl^alvl 


;check, alloc vectors 


dw 


xlt2,0000h 


; translate table 


dw 


0000h,0000h 


;scratch area 


dw 


dirbuf,dpb2 


;dir buff,parm block 


dw 


csv2,alv2 


;check, alloc vectors 


dw 


xlt3,0000h 


;translate table 


dw 


0000h,0000h 


;scratch area 


dw 


dirbuf,dpb3 


;dir buff,parm block 


dw 


csv3,alv3 


;check, alloc vectors 


diskdef 


0,1,26,6,1024 


,243, 64, 64, offset 


equ 


$ 


?disk parm block 


dw 


26 


;sec per track 


db 


3 


;block shift 


db 


7 


;block mask 


db 





;extnt mask 


dw 


242 


;disk size-1 


dw 


63 


ydirectory max 


db 


192 


;alloc0 


db 





;allocl 


dw 


16 


;check size 


dw 


2 


;of fset 


equ 


5 


; translate table 


db 


1 




db 


7 




db 


13 




db 


19 




db 


25 




db 


5 




db 


11 




db 


17 




db 


23 




db 


3 
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4a8c+09 




db 


9 


4a8d+0£ 




db 


15 


4a8e+15 




db 


21 


4a8f+02 




db 


2 


4a90+08 




db 


8 


4a91-i-0e 




db 


14 


4a92+14 




db 


20 


4a93+la 




db 


26 


4a94+06 




db 


6 


4a95+0c 




db 


12 


4a96+12 




db 


18 


4a97+18 




db 


24 


4a98+04 




db 


4 


4a99+0a 




db 


10 


4a9a+10 




db 


16 


4a9b+16 




db 


22 






diskdef 


1,0 


4a73+= 


dpbl 


egu 


dpb0 


001f+= 


alsl 


equ 


als0 


0010+= 


cssl 


equ 


CSS0 


4a82+= 


xltl 


eau 


Xlt0 






diskdef 


2,0 


4a73+= 


clpb2 


equ 


dpb0 


001f+= 


als2 


equ 


als0 


0010-i-= 


css2 


equ 


CSS0 


4a82+= 


xlt2 


equ 


xlt0 






diskdef 


3,0 


4a73+= 


dpb3 


equ 


dpb0 


001f+= 


als3 


equ 


als0 


0010+= 


css3 


equ 


CSS0 


4a82+= 


xlt3 


equ 


Xlt0 




; 


endef occurs 



;eguivalent parameters 
;same allocation vector size 
;same checksum vector size 
;same translate table 

;equivalent parameters 
;same allocation vector size 
;same checksum vector size 
;same translate table 

;equivalent parameters 
;same allocation vector size 
;same checksum vector size 
;same translate table 
at end of assembly 



00£d 
00fc 
00£3 
007e 



revrt 
into 
icon 
inte 



end of controller - independent code^ the remaini 
are tailored to the particular operating environm 
be altered for any system which differs from the 

the following code assumes the mds monitor exists 
and uses the i/o subroutines within the monitor 

we also assume the mds system has four disk drive 

equ 0fdh ; interrupt revert port 

equ 0fch ; interrupt mask port 

equ 0f3h ; interrupt control port 

equ 0111$1110b;enable rst 0(warm boot) ,rst 7 



f800 
ff0f 
f803 
f806 
f809 
f80c 
f80f 
f812 



; mds monitor equates 

mon80 equ 0f800h ;mds monitor 

rmon80 equ 0ff0fh ;restart mon80 (boot error) 

ci equ 0f803h ;console character to reg-a 

ri equ 0f806h ;reader in to reg-a 

CO equ 0f809h ;console char from c to console o 

po equ 0f80ch ;punch char from c to punch devic 

lo equ 0f80fh ;list from c to list device 

csts equ 0f81.2h ;console status 00/ff to register 
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0078 
0078 
0079 
007b 

0079 
007a 

0004 
0006 
0003 
0004 
000d 
000a 



4a9c 0d0a0a 
4a9f 3230 
4aal 6b2043£ 
4aad 322e30 
4ab0 0d0a00 



base 

dstat 

rtype 

rbyte 

f 

ilow 

ihigh 

readf 

wr itf 

recal 

iordy 

cr 

If 

• 

signon: 



boot: 



4ab3 310001 
4ab6 219c4a 
4ab9 cdd34b 
4abc af 
4abd 320400 
4ac0 c30f4b 



disk ports and commands 

equ 78h ;base of disk command io ports 

equ base ;disk status (input) 

equ base+1 ; result type (input) 

equ base+3 ; result byte (input) 

equ base+1 ;iopb low address (output) 

equ base+2 ;iopb high address (output) 

equ 4h ;read function 

equ 6h ; write function 

equ 3h ;recalibrate drive 

equ 4h ; i/o finished mask 

equ 0dh ;carriage return 

equ 0ah ;line feed 

;signon message: xxk cp/m vers y.y 

db cr,lf,lf 

db •20' ; sample memory size 

db * k cp/m vers ' 

db vers/10+'0' , • . • rvers mod 10+'0' 

db cr,lf,0 

;print signon message and go to ccp 

(note: mds boot initialized iobyte at 0003h) 

Ixi sp,buff+80h 

Ixi h, signon 

call prmsg ;print message 

xra a ?clear accumulator 

sta cdisk ;set initially to disk a 

jmp gocpm ;go to cp/m 



wboot:; loader on track 0, sector 1, which will be skippe 
read cp/m from disk - assuming there is a 128 byt 
start. 



4ac3 3180( 

4ac6 0e0a 
4ac8 c5 

4ac9 010034 
4acc cdbb4b 
4acf 0e00 
4adl cd7d4b 
4ad4 0e00 
4ad6 cda74b 
4ad9 0e02 
4adb cdac4b 



wboot0: 



Ixi 



sp.buff ;using dma - thus 80 thru ff ok f 



mvi c^retry ;max retries 

push b 

;enter here on error retries 

Ixi b,cpmb ;set dma address to start of disk 

call setdma 

mvi c,0 ;boot from drive 

call seldsk 

mvi c,0 

call settrk ;start with track 

mvi c^2 ;start reading sector 2 

call setsec 



4ade cl 
4adf 062c 



read sectors, count nsects to zero 
pop b ;10-error count 
mvi b, nsects 
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rdsec: 


;read n 


ext sector 




4ael 


c5 


push 


b 


;save sector count 




4ae2 


cdcl4b 


call 


read 






4ae5 


c2494b 


jnz 


booterr 


;retry if errors occur 




4ae8 


2a6c4c 


Ihld 


iod 


; increment dma address 




4aeb 


118000 


Ixi 


d,128 


;sector size 




4aee 


19 


dad 


d 


; incremented dma address in 


4ae£ 


44 


inov 


b,h 






4af0 


4d 


mov 


c,l 


;ready for call to set 


dma 


4afl 


cdbb4b 


call 


setdma 






4af4 


3a6b4c 


Ida 


ios 


;sector number just read 


4af7 


fela 


cpi 


26 


;read last sector? 




4af9 


da054b 


jc 


rdl 








; 


must be 


sector 


26, zero and go to next 


track 


4a fc 


3d6a4c 


Ida 


lot 


;get track to register 


a 


4aff 


3c 


inr 


a 






4b00 


4f 


mov 


c,a 


;readY for call 




4b01 


cda74b 


call 


settrk 






4b04 


af 


xra 


a 


; clear sector number 




4b05 


3c rdl: 


inr 


a 


;to next sector 




4b06 


4f 


mov 


c,a 


;ready for call 




4b07 


cdac4b 


call 


setsec 






4b0a 


cl 


pop 


b 


; recall sector count 




4b0b 


05 


dcr 


b 


;done? 




4b0c 


c2el4a 


jnz 


rdsec 







4b0£ 


£3 


4bl0 


3el2 


4bl2 


d3fd 


4bl4 


a£ 


4bl5 


d3fc 


4bl7 


3e7e 


4bl9 


d3fc 


4blb 


af 


4blc 


d3f3 


4ble 


018000 


4b21 


cdbb4b 


4b24 


3ec3 


4b26 


320000 


4b29 


21034a 


4b2c 


220100 


4b2f 


320500 


4b32 


21063c 


4b35 


220600 


4b38 


323800 


4b3b 


2100£8 


4b3e 


223900 



; done with the load, reset default buffer address 
gocpm: ; (enter here from cold start boot) 
; enable rst0 and rst? 
di 

; initialize command 



;cleared 

;rst0 and rst? bits on 



mvi 


a,12h 


out 


revrt 


xra 


a 


out 


into 


mvi 


a,inte 


out 


into 


xra 


a 


out 


icon 



; interrupt control 



set default buffer address to d0h 
Ixi b,buff 
call setdma 

reset monitor entry points 



;jmp wboot at location 00 



;jmp bdos at location 5 

?jmp to mon80 (may have been chan 



mvi 


a.Dmp 


sta 





Ixi 


h,wboote 


shld 


1 


sta 


5 


Ixi 


h,bdos 


shld 


6 


sta 


7*8 


Ixi 


h,mon80 


shld 


7*8+1 



leave iobyte set 
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; previously selected disk was b^ send parameter to 

4b41 3a0400 Ida cdisk ;last logged disk number 

4b44 4f mov c,a ;send to ccp to log it in 

4b45 fb ei 

4b46 C30034 jmp cpmb 

7 

; error condition occurred, print message and retry 

booterr: 

4b49 cl pop b ; recall counts 

4b4a 0d dcr c 

4b4b ca524b jz booter0 

; try again 

4b4e c5 push b 

4b4f c3c94a jmp wboot0 

booter0: 

; otherwise too many retries 

4b52 215b4b Ixi h,bootmsg 

4b55 cdd34b call prmsg 

4b58 c30fff jmp rmon80 ;mds hardware monitor 

7 

bootmsg: 

4b5b 3f626f4 db •?boot\0 

? 

» 

const: ;console status to reg-a 

; (exactly the same as mds call) 

4b61 c312f8 jmp csts 

conin: ;console character to reg-a 

4b64 cd03f8 call ci 

4b67 e67f ani 7fh ;remove parity bit 

4b69 c9 ret 

conout: ;console character from c to console out 

4b6a c309f8 jmp co 



4b6d c30ff8 



list: ylist device out 

(exactly the same as mds call) 
jmp lo 



listst: 

;return list status 
4b70 a£ xra a 

4b71 c9 ret ;always not ready 



4b72 c30cf8 



4b75 c306f8 



punch: ; punch device out 

(exactly the same as mds call) 
jmp po 

reader: ; reader character in to reg-a 
(exactly the same as mds call) 
jmp ri 

home: ;move to home position 
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4b78 0e00 
4b7a c3a74b 



4b7d 210000 
4b80 79 
4b81 fe04 
4b83 cl0 

4b84 e602 
4b86 32664c 
4b89 79 
4b8a e601 
4b8c b7 
4b8d ca924b 
4b90 3e30 



4b92 
4b93 
4b96 
4b97 
4b99 
4b9a 

im 
4b9e 
4b9£ 
4ba0 
4bal 
4ba2 
4ba5 
4ba6 



47 

21684c 

7e 

e6c£ 

b0 

77 

!i00 

29 

29 

29 

29 

11334a 

19 

c9 



; treat a: 
mvi 
jmp 

t 

seldsk: ; select 
Ixi 
mov 
cpi 
rnc 

ani 
sta 
mov 
ani 
ora 

jz 
mvi 
setdrive: 

mov 
Ixi 
mov 
ani 
ora 
mov 



dad 
dad 
dad 
dad 
Ixi 
dad 
ret 



; track 00 seek 

c,0 

settrk 

disk given by register c 

h,0000h ;return 0000 if error 

a,c 

ndisks ;too large? 

;leave hi = 0000 

10b ;00 00 for drive 0,1 and 10 10 fo 

dbank ;to select drive bank 

a,c ;00, 01, 10, 11 

lb ;mds has 0,1 at 78, 2,3 at 88 

a ;result 00? 

setdrive 

a, 00110000b ;selects drive 1 in bank 



b,a 
h,iof 
a,m 
11001111b 



;save the function 
;io function 



b 
m,a 



;mask out disk number 



;mask in new disk number 
;save it in iopb 



;hl=disk number 
h . ;*2 
h ;*4 
h ;*8 
h ;*16 
d,dpbase 
d ;hl=disk ^header table address 



4ba7 216a4c 
4baa 71 
4bab c9 



settrk: 



;set 
Ixi 
mov 
ret 



track address given by c 
h,iot 
m,c 



4bac 216b4c 
4baf 71 
4bb0 c9 



setsec: 



;set 
Ixi 
mov 
ret 



sectran: 



4bbl 0600 

4bb3 eb 

4bb4 09 

4bb5 7e 

4bb6 326b4c 



mvi 

xchg 

dad 

mov 

sta 

mov 
ret 



sector number given by c 
h,ios 

m,c 



; translate sector be using table at de 
b,0 ;double precision sector number 

; translate table address to hi 
b ; translate (sector) address 
a,m ; translated sector number to a 
ios 
l,a ; return sector number in 1 



setdma: ;set dma address given by regs b,c 
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4bbb 69 
4bbc 60 
4bbd 226c4c 
4bc0 c9 



mov 


l,c 


mov 


h,b 


shld 


iod 


ret 





4bcl 0e04 

4bc3 cde04b 

4bc6 cd£04b 

4bc9 c9 



read: ;read next disk record (assuming disk/trk/sec/dma 

mvi c,readf ;set to read function 

call setfunc 

call waitio ;perform read function 

ret ;may have error set in reg-a 



4bca 0e06 
4bcc cde04b 
4bcf cdf04b 
4bd2 c9 



write: ;disk write function 

mvi c,writf 

call setfunc ;set to write function 

call waitio 

ret ?maY have error set 



4bd3 7e 
4bd4 b7 
4bd5 c8 

4bd6 e5 
4bd7 4f 
4bd8 cd6a4b 
4bdb el 
4bdc 23 
4bdd c3d34b 



utility subroutines 
prmsg: ;print message at h^l to 

mov arm 

ora a ;zero? 

rz 
; more to print 

push h 

mov c^a 

call conout 

pop h 

inx h 

jmp prmsg 



setfunc: 



4be0^ 21684c 
4be3 7e 
4be4 e6f8 
4be6 bl 
4be7 77 



4be8 e620 
4bea 216b4c 
4bed b6 
4bee 77 
4bef c9 



set function for next i/o (command in reg-c) 

Ixi h,iof ;io function address 

mov a,m ;get it to accumulator for maskin 

ani 11111000b ; remove previous command 

ora c ;set to new command 

mov m,a ; replaced in iopb 

the mds-800 controller req's disk bank bit in sec 

mask the bit from the current i/o function 

ani 00100000b ;mask the disk select bit 

Ixi h,ios ;address the sector selec 

ora m ; select proper disk bank 

mov m,a ;set disk select bit on/o 

ret 



4bf0 0e0a 



waitio: 



mvi 



rewait: 



4bf2 cd3f4c 
4bf5 cd4c4c 

4bf8 3a664c 



c, retry ;max retries before perm error 



start the i/o function and wait for completion 

call intype ;in rtype 

call inbyte ;clears the controller 



Ida 



dbank 



;set bank flags 
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4bfb b7 
4bfc 3e67 
4b£e 064c 
4c00 c20b4c 
4c03 d379 
4c05 78 
4c06 d37a 
4c08 c3104c 



4c0b d389 
4c0d 78 
4c0e d38a 



4g10 cd594c wait0: 
4cl3 e604 
4cl5 cal04c 



4cl8 cd3f4c 



4clb £e02 
4cld ca324c 



4c20 b7 
4c21 c2384c 



4c24 cd4c4c 
4c27 17 
4c28 da324c 
4c2b If 
4c2c e6£e 
4c2e c2384c 



4c31 c9 



4c32 cd4c4c 
4c35 c3384c 



ora 
mvi 
mvi 
jnz 
out 
mov 
out 
jmp 



a ;zero if drive 0,1 and nz 

a,iopb and 0ffh ;low address for iopb 

b,iopb shr 8 ;high address for iopb 

iodrl ;drive bank 1? 

ilow ;low address to controlle 

a,b 

ihigh ;high address 



wait0 



iodrl: ; drive bank 1 



out 
mov 
out 

call 

ani 

jz 



ilow+10h 

a,b 

ihigh+10h 

instat 

iordy 

wait0 



;to wait for complete 
;88 for drive bank 10 



;wait for completion 
; ready? 



check io completion ok 

call intype ;must be io complete (00) 

00 unlinked i/o complete, 01 linked i/o comple 

10 disk status changed 11 (not used) 

cpi 10b ; ready status change? 

jz wready 

must be 00 in the accumulator 

ora a 

jnz werror 



check i/o error bits 

call inbyte 

ral 

jc wready 

rar 

ani 11111110b 

jnz werror 



;some other condition, re 

;unit not ready 
;any other errors? 



; read or write is ok, accumulator contains zero 
ret 

wready: ;not ready, treat as error for now 

call inbyte ;clear result byte 

jmp try count 

9 

werror: ;return hardware malfunction (crc, track, seek, e 
the mds controller has returned a bit in each pos 
of the accumulator, corresponding to the conditio 

- deleted data (accepted as ok above) 

1 - crc error 

2 - seek error 

3 - address error (hardware malfunction) 

4 - data over/under flow (hardware malfunct 

5 - write protect (treated as not ready) 

6 - write error (hardware malfunction) 

7 - not ready 
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(accumulator bits are numbered 76543210) 



4c38 0cl 
4c39 c2f24b 



; it may be useful to filter out the various condit 

; but we will get a permanent error message if it i 

; recoverable, in any case, the not ready conditio 

; treated as a separate condition for later improve 

trycount: 

; register c contains retry count, decrement 'til z 

dcr c 

jnz rewait ;for another try 



4c3c 3e01 
4c3e c9 



cannot recover from error 
mvi a,l ;error code 
ret 



4c3f 3a664c 
4c42 b7 
4c43 c2494c 
4c46 db79 
4c48 c9 
4c49 db89 
4c4b c9 



; intype, inbyte, instat read drive bank 00 or 10 
in type: Ida dbank 

a 

intypl ;skip to bank 10 

rtype 



ora 
jnz 
in 
ret 
intypl: in 
ret 



rtype+10h 



;78 for 0,1 88 for 2,3 



4c4c 3a664c 
4c4f b7 
4c50 c2564c 
4c53 db7b 
4c55 c9 
4c56 db8b 
4c58 c9 



inbyte: Ida 
ora 
jnz 
in 
ret 

inbytl: in 
ret 



dbank 
a 

inbytl 
rbyte 

rbyte+10h 



4c59 3a664c 
4c5c b7 
4c5d c2634c 
4c60 db78 
4c62 c9 
4c63 db88 
4c65 c9 



4c66 00 



4c67 80 

4c68 04 

4c69 01 

4c6a 02 

4c6b 01 

4c6c 8000 



instat: Ida 
ora 
jnz 
in 
ret 

instal: in 
ret 



dbank: 

iopb: 

iof : 
ion: 
iot: 
ios: 
iod: 



dbank 
a 

instal 
dstat 

dstat+10h 



data areas (must be in ram) 
db ;disk bank 00 if drive 0,1 
; 10 if drive 2,3 

;io parameter block 

db 80h ;normal i/o operation 
db readf ; io function, initial read 
db 1 ; number of sectors to read 
db offset ; track number 
db 1 ; sector number 
dw buff ;io address 



define ram areas for bdos operation 
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endef 



4c6e+= 


beg da t 


equ 


$ 


4c6e+ 


dirbuf: 


ds 


128 


4cee+ 


alv0: 


ds 


31 


4d0d+ 


CSV0: 


ds 


16 


4aicl+ 


alvl: 


ds 


31 


4d3c+ 


csvl: 


ds 


1§ 


4d4c+ 


alv2: 


ds 


31 


4d6b+ 


csv2: 


ds 


16 


4d7b+ 


alv3: 


ds 


31 


4d9a+ 


csv3: 


ds 


16 


4daa+= 


enddat 


equ 


$ 


013c+= 


datsiz 


equ 


$-begdat 


4daa 




end 





;directory access buffer 
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APPENDIX C: A SKELETAL CBIOS 



0014 ^ 



msize 



skeletal cbios for first level of cp/m 2.0 altera 

equ 20 ;cp/m version memory size in kilo 

"bias" is address offset from 3400h for memory sy 
than 16k (referred to as "b" throughout the text) 



0000 


= 


bias 


equ 


(msize-20)*1024 






3400 


= 


ccp 


equ 


3400h+bias ; 


base of ccp 




3c06 


= 


bdos 


equ 


ccp+806h ; 


base of bdos 




4a00 


= 


bios 


equ 


ccp+1600h ; 


base of bios 




0004 


= 


cdisk 


equ 


0004h ?current 


disk number 0=a, . , 


.rl5=p 


0003 


=: 


iobyte 

• 


equ 


0003h ; Intel i/o byte 




4a00 




f 


org 


bios ;origin of this program 




002c 


= 


nsects 

• 


equ 


($-ccp)/128 J 


warm start sector 


count 








] 


ump 


vector for individual subroutines 




4a00 


c39c4a 




; 


mp 


boot ; 


cold start 




4a03 


c3a64a 


wboote: 




imp 


wboot j 


warm start 




4a06 


c3114b 






mp 


const J 


console status 




4a09 


c3244b 






mp 


conin j 


console character 


in 


4a0c 


c3374b 






imp 


conout ; 


console character 


out 


4a0f 


c3494b 






imp 


list ; 


►list character out 


4al2 


c34d4b 






imp 


punch , 


•punch character out 


4al5 


c34f4b 






imp 


reader , 


f reader character out 


4al8 


c3544b 






imp 


home 


fmove head to home 


positi 


4alb 


c35a4b 






imp 


seldsk 


Fselect disk 




4ale 


c37d4b 






imp 


settrk 


fset track number 




4a21 


c3924b 






imp 


setsec , 


•set sector number 




4a24 


c3ad4b 






imp 


setdma ; 


•set dma address 




4a27 


c3c34b 






imp 


read , 


•read disk 




4a2a 


c3d64b 






imp 


write ^ 


•write disk 




4a2a 


c34b4b 






imp 


listst ; 


•return list status 


4a30 


c3a74b 






imp 


sectran ; 


•sector translate 





4a33 734a00 dpbase: 
4a37 000000 
4a3b f04c8d 
4a3f ec4d70 

4a43 734a00 
4a47 000000 
4a4b f04c8d 
4a4f fc4d8f 

4a53 734a00 
4a57 000000 
4a5b f04c8d 
4a5f 0c4eae 



fixed data tables for four-drive standard 

ibm-compatible 8" disks 

disk parameter header for disk 00 

dw trans, 0000h 

dw 0000h,0000h 

dw dirbf^dpblk 

dw chk00,all00 

disk parameter header for disk 01 

dw trans, 0000h 

dw 0000h,0000h 

dw dirbf,dpblk 

dw chk01,all01 

disk parameter header for disk 02 

dw trans, 0000h 

dw 0000h,0000h 

dw dirbf,dpblk 

dw chk02,all02 
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4a63 734a00 


dw 


4a67 000000 


dw 


4a6b f04c8d 


dw 


4a6f lc4ecd 


dw 


7 

• 
t 


se 


\m mm ^"-' 


^g 


4a7b 170309 


db 


4a7f 150208 


db 


4a83 141306 


db 


4a87 121804 


db 


4a8b 1016 


db 


dpblk : 


;d. 


4a8d la00 


dw 


4a8£ 03 


db 


4a90 07 


db 


4a91 00 


db 


4a92 £200 


dw 


4a94 3f00 


dw 


4a96 c0 


db 


4a97 00 


db 


4a98 1000 


dw 


4a9a 0200 


dw 



boot: 



4a9c a£ 
4a9d 320300 
4aa0 320400 
4aa3 c3e£4a 

4aa6 318000 
4aa9 0e00 
4aab cd5a4b 
4aae cd544b 

4abl 062c 
4ab3 0600 
4ab5 1602 



4ab7 210034 

4aba c5 
4abb d5 
4abc e5 
4abd 4a 
4abe cd924b 
4acl cl 



loadl! 



disk parameter header for disk 03 
trans, 0000h 
0000h,0000h 
dirbf, dpblk 
chk03,all03 



sector translate vector 

i5l5^h!?7 

23,3r9,15 

21,2,8,14 

20,26,6,12 

18,24,4,10 

16,22 



}iigl8fi l\hVA 

;sectors 9,10,11,12 

•sectors 13,14,15,16 

;sectors 17,18,19,20 

;sectors 21,22,23,24 

;sectors 25,26 



;disk parameter block, common to all disks 



26 

3 

7 



242 

63 

192 



16 

2 



end of fixed tables 



^sectors per track 
fblock shift factor 
fblock mask 
fnull mask 
fdisk size-1 
fdirectory max 
?alloc 
?alloc 1 
^check size 
ftrack offset 



individual subroutines to perform each function 

;simplest case is to just perform parameter initi 

xra a 

sta iobyte 

sta cdisk 

jmp gocpm 



?zero in the accum 
;clear the iobyte 
;select disk zero 
; initialize and go to cp/ 



wboot: ; simplest case is to read the disk until all sect 



Ixi 
mvi 
call 
call 

mvi 

mvi 

mvi 

note 

conta 

Ixi 

;load 

push 

push 

push 

mov 

call 

pop 



sp,80h 
c,0 

seldsk 
home 



;use space below buffer f 
;select disk 

;go to track 00 



b,nsects ;b counts # of sectors to 
c,0 ;c has the current track 

d,2 ;d has the next sector to 

that we begin by reading track 0, sector 2 s 
ins the cold start loader, which is skipped 

h,ccp ;base of cp/m (initial lo 

one more sector 

b ;save sector count, current track 

d ;save next sector to read 

h ;save dma address 

c,d ;get sector address to register c 

setsec ;set sector address from register 

b ; recall dma address to b,c 
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4ac2 c5 
4ac3 cdad4b 



4ac6 cdc34b 
4ac9 fe00 
4acb c2a64a 



4ace el 

4acf 118000 

4ad2 19 

4ad3 dl 

4ad4 cl 

4ad5 05 

4ad6 cae£4a 



4ad9 14 
4ada 7a 
4adb felb 
4add daba4a 



4ae0 1601 
4ae2 0c 



4ae3 c5 
4a64 d5 
4ae5 e5 
4ae6 cd7d4b 
4ae9 el 
4aea dl 
4aeb cl 
4aec c3ba4a 



4aef 3ec3 
4afl 320000 
4a£4 21034a 
4af7 220100 

4a£a 320500 
4a£d 21063c 
4b00 220600 

4b03 018000 
4b06 cdad4b 

4b09 fb 
4b0a 3a0400 
4b0d 4£ 
4b0e C30034 



gocpm: 



push b ; replace on stack £or later recal 
call setdma ?set dma address from b,c 

drive set to 0, track set, sector set, dma addres 

call read 

cpi 00h ;any errors? 

jnz wboot ; retry the entire boot i£ an erro 

no error, move to next sector 

pop h ; recall dma address 

Ixi d,128 ;dma=dma+128 

dad d ;new dma address is in h,l 

pop d ; recall sector address 

pop b ; recall number o£ sectors remaini 

dcr b ;sectors=sectors-l 

J2 gocpm ? transfer to cp/m if all have bee 

more sectors remain to load, check for track chan 

inr d 

mov a,d 7sector=27?, if so, change tracks 

cpi 27 

jc loadl ;carry generated if sector<27 

end of current track, go to next track 

mvi d,l ;begin with first sector of next 

inr c ;track=track+l 

save register state, and change tracks 

push b 

push d 

push h 

call settrk ;track address set from register 

pop h 

pop d 

pop b 

jmp loadl ?for another sector 

end of load operation, set parameters and go to c 



mvi 
sta 
Ixi 
shld 

sta 
Ixi 
shld 

Ixi 
call 

ei 
Ida 
mov 
jmp 



a,0c3h ;c3 is a jmp instruction 

;for jmp to wboot 
h,wboote ;wboot entry point 

1 ?set address field for jmp at 

5 ;for jmp to bdos 
h,bdos ;bdos entry point 

6 ;address field of jump at 5 to bd 

;default dma address is 80h 



b,80h 
setdma 



cdisk 

c,a 

ccp 



;enable the interrupt system 

;get current disk number 

;send to the ccp 

;go to cp/m for further processin 
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simple i/o handlers (must be filled in by user) 
in each case, the entry point is provided, with s 
to insert your own code 

const: ;console status, return 0ffh if character ready, 

4bll ds 10h ; space for status subroutine 

4b21 3e00 mvi a,00h 

4b23 c9 ret 

9 

conin: ;console character into register a 

4b24 ds 10h ; space for input routine 

4b34 e67f ani 7fh ;strip parity bit 

4b36 c9 ret 

conout: ; console character output from register c 
4b37 79 mov a,c ;get to accumulator 

4b38 ds 10h ; space for output routine 

4b48 c9 ret 

list: ;list character from register c 
4b49 79 mov a,c ;character to register a 

4b4a c9 ret ;null subroutine 

listst: ; return list status (0 if not ready, 1 if ready) 
4b4b af xra a ;0 is always ok to return 

4b4c c9 ret 

9 

punch: ;punch character from register c 
4b4d 79 mov a,c ;character to register a 

4b4e c9 ret ;null subroutine 

reader: ;read character into register a from reader devic 
4b4f 3ela mvi a,lah ;enter end of file for now (repla 

4b51 e67f ani 7fh ; remember to strip parity bit 

4b53 c9 ret 



i/o drivers for the disk follow 

for now, we will simply store the parameters away 

in the read and write subroutines 



4b54 0e00 
4b56 cd7d4b 
4b59 c9 



home: ;move to the track 00 position of current drive 
; translate this call into a settrk call with param 

mvi c,0 ;select track 

call settrk 

ret ;we will move to 00 on first read 



4b5a 210000 
4b5d 79 
4b5e 32ef4c 
4b61 fe04 



seldsk: ;select disk given by register c 

Ixi h,0000h ;error return code 

mov a , c 

sta diskno 

cpi 4 ;must be between and 3 
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4b63 d0 

4b64 

4b6e 3aef4c 
4b71 6f 
4b72 2600 
4b74 29 
4b75 29 
4b76 29 
4b77 29 
4b78 11334a 
4b7b 19 
4b7c c9 



rnc ;no carry if 4,5r.,. 

disk number is in the proper range 

ds 10 ; space for disk select 

compute proper disk parameter header address 



Ida 


diskno 




mov 


l.a 


;l=disk number 0,1,2,3 


mvi 


h,0 


;high order zero 


dad 


h 


;*2 


dad 


h 


;*4 


dad 


h 


;*8 


dad 


h 


;*16 (size of each header) 


Ixi 


d,dpbase 


dad 


d 


;hl=.dpbase(diskno*16) 


ret 







settrk: ;set track given by register c 
4b7d 79 mov a,c 
4b7e 32e94c sta track 

4b81 ds 10h ; space for track select 

4b91 c9 ret 

setsec: ;set sector given by register c 
4b92 79 mov a,c 

4b93 32eb4c sta sector 

4b96 ds 10h ; space for sector select 

4ba6 c9 ret 



sectran: 



4ba7 eb 
4ba8 09 
4ba9 6e 
4baa 2600 
4bac c9 



4bad 69 
4bae 60 
4baf 22ed4c 
4bb2 
4bc2 c9 



; translate the sector given by be using the 
; translate table given by de 



xchg 

dad 

mov 

mvi 

ret 



b 

l,m 

h,0 



hl=. trans 
hl=. trans (sector) 
1 = trans (sector) 
hl= trans (sector) 
with value in hi 



setdma: ?set dma address given by registers b and c 



mov 

mov 

shld 

ds 

ret 



l,c ;low order address 

h,b ;high order address 

dmaad ;save the address 

10h ; space for setting the dma addres 



read: 



4bc3 

4bd3 c3e64b 



4bd6 



;perform read operation (usually this is similar 

so we will allow space to set up read command, th 

common code in write) 

ds 10h ;set up read command 

jmp waitio ;to perform the actual i/o 

; perform a write operation 

ds 10h ;set up write commanu 

waitio: ;enter here from read and write to perform the ac 
7 operation, return a 00h in register a if the ope 
; properly, and 01h if an error occurs during the r 



write: 
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• 
9 






4be6 


; 


ds 


256 


4ce6 3e01 




mvi 


a,l 


4ce8 c9 




ret 





in this case, we have saved the disk number in 'd 
the track number in 'track' (0-76 
the sector number in 'sector' (1- 
the dma address in 'dmaad' (0-655 
; space reserved for i/o drivers 
;error condition 
; replaced when filled-in 

the remainder of the cblos is reserved unlnitiali 
data area, and does not need to be a part of the 
system memory image (the space must be available, 
however, between "begdat" and **enddat*'). 



4ce9 


track: 


ds 


2 


4ceb 


sector: 


ds 


2 


4ced 


dmaad: 


ds 


2 


4ce£ 


diskno: 


ds 


1 




1 
i 


scratch 


ram 


4cf0 = 


beg da t 


equ 


$ 


4c£0 


dirbf: 


ds 


128 


4cl70 


all00: 


ds 


31 


4d8£ 


all01: 


ds 


31 


4dae 


all02: 


ds 


31 


4dcd 


all03: 


ds 


31 


4dec 


chk00: 


ds 


16 


4d£c 


chk01: 


ds 


16 


4e0c 


chk02: 


ds 


16 


4elc 


chk03: 


ds 


16 


4e2c ° 


enddat 


equ 


S 


013c = 


datsiz 


equ 


$-b 


4e2c 




end 





;two bytes for expansion 
;two bytes for expansion 
;direct memory address 
;disk number 0-15 

area for bdos use 

; beginning of data area 
;scratch directory area 
;allocation vector 
jallocation vector 1 
;allocation vector 2 
;allocation vector 3 
; check vector 
; check vector 1 
; check vector 2 
; check vector 3 



;end of data area 
$-begdat;size of data area 



196 



0100 

0014 



3400 
3c00 
4a00 



APPENDIX D: A SKELETAL GETSYS/PUTSYS PROGRAM 

; combined getsys and putsys programs from Sec 4, 
; Start the programs at the base of the TPA 



msize 
; *'bias 



bias 
ccp 
bdos 
bios 



org 
egu 



0100h 
20 



size of cp/m in Kbytes 



• is the amount to add to addresses for > 20k 
(referred to as •*b" throughout the text) 

equ (msize-20) *1024 

equ 3400h-t-bias 

equ ccp+0800h 

equ ccp+1600h 

getsys programs tracks and 1 to memory at 
3880h + bias 



01i30 
0103 
0106 



318033 
218033 
0600 



0108 0e01 



010a 
010d 
0110 
0111 
0112 
0113 
0115 



0118 
0119 
011a 
011c 



011f 
0120 



cd0003 

118000 

19 

0c 

79 

felb 

da0a01 



04 
78 

fe02 
da0801 



gstart: 

rd$trk: 
rd$sec: 



register 
a 
b 
c 

d,e 
h,l 
sp 



usage 
(scratch register) 
track count (0.,.76) 
sector count (1,..26) 
(scratch register pair) 
load address 
set to stack address 



Ixi 
Ixi 
mvi 

mvi 

call 

Ixi 

dad 

inr 

mov 

cpi 

jc 



sprccp-0080h 

h^ccp-0080h 

b,0 

c,l 

read$sec 

d,128 

d 

c 

a,c 

27 

rdsec 



start of getsys 
convenient plac 
set initial loa 
start with trac 
read next track 
each track star 

get the next se 
offset by one s 

(hl=hl+128) 
next sector 
fetch sector nu 

and see if la 
<r do one more 



arrive here at end of tracks move to next track 



xnr 
mov 
cpi 
jc 



b 

a,b 
2 
rd$trk 



track = track+1 
check for last 
track = 2 ? 
<, do another 



arrive here at end of load, halt for lack of anything b 



fb 
76 



ei 
hit 
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0200 



putsys program r places memory image starting at 

3880h -f bias back to tracks and 1 

start this program at the next page boundary 

org ($+0100h) and 0£f00h 



0200 318033 
0203 218033 
0206 0600 

0208 0e01 

020a cd0004 
020d 118000 

0210 19 

0211 0c 

0212 79 

0213 felb 
0215 da0a02 



0218 04 

0219 78 
021a £e02 
021c da0802 



021£ fb 
0220 76 



put$sys: 



wr$trk: 
wr$sec: 



Ixi sp,ccp-0080h 

Ixi hrccp-0080h 

mvi b,0 

mvi Crl 

call write$sec 

Ixi d,128 

dad d 

inr c 

mov a^c 

cpi 27 

jc wr$sec 



convenient plac 
start of dump 
start with trac 

start with sect 

write one secto 
length of each 
<hl>=<hl> + 128 
<c> = <c> + 1 
see if 

past end of t 
nOr do another 



arrive here at end of track, move to next track 



inr 
mov 
cpi 
jc 



b 

a,b 
2 
wr$trk 



track = track+1 
see if 

last track 
no, do another 



done with putsys, halt for lack of anything bette 



ei 

hit 



0300 



0300 c5 

0301 e5 



0302 

0342 el 

0343 cl 



; user supplied subroutines for sector read and write 

; move to next page boundary 

org ($+0100h) and 0ff00h 

read$sec; 

; read the next sector 

; track in <b>, 

; sector in <c> 

; dmaaddr in <hl> 



push 
push 



b 
h 



; user defined read operation goes here 
ds 64 



pop 
pop 



h 
b 
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0344 c9 ret 

0400 org ($+0100h) and 0£f00h ; another page bo 
write$sec: 

; same parameters as read$sec 

0400 c5 push b 

0401 eS push h 

; user defined write operation goes here 

0402 ds 64 

0442 el pop h 

0443 cl pop b 

0444 c9 ret 

; end of getsys/putsys program 

0445 end 



199 



APPENDIX E: A SKELETAL COLD START LOADER 



this is a sample cold start loader which, when modified 
resides on track 00, sector 01 (the first sector on the 
diskette) . we assume that the controller has loaded 
this sector into memory upon system start-up (this pro- 
gram can be keyed-in^ or can exist in read/only memory 
beyond the address space of the cp/m version you are 
running), the cold start loader brings the cp/m system 
into memory at "loadp** (3400h + •'bias*'), in a 20k 
memory system, the value of "bias" is 0000h, with large 
values for increased memory sizes (see section 2) . af te 
loading the cp/m system, the clod start loader branches 
to the "boot" entry point of the bios, which begins at 
"bios" + "bias." the cold start loader is not used un- 
til the system is powered up again, as long as the bios 
is not overwritten, the origin is assumed at 0000hr an 
must be changed if the controller brings the cold start 
loader into another area, or if a read/only memory area 
is used. 



0000 



org 



0014 = 


msize 


egu 


20 


0000 ^ 


bias 


egu 


(msize-20)*1024 


3400 = 


ccp 


equ 


3400h+bias 


4a00 = 


bios 


equ 


ccp+1600h 


0300 = 


biosl 


equ 


0300h 


4a00 = 


boot 


equ 


bios 


1900 = 


size 


equ 


bios+biosl-ccp 


0032 = 


sects 


equ 


size/128 



; base of ram in cp/m 

; min mem size in kbytes 

; offset from 20k system 

; base of the ccp 

; base of the bios 

; length of the bios 

; size of cp/m system 

; # of sectors to load 



begin the load operation 



cold: 



0000 010200 


Ixi 


b,2 


0003 1632 


mvi 


d, sects 


0005 210034 


Ixi 


h,ccp 



b=0, c=sector 2 
d=# sectors to load 
base transfer address 



Isect: 



load the next sector 



insert inline code at this point to 
read one 128 byte sector from the 
track given in register b, sector 
given in register c, 
into the address given by <hl> 

branch to location "cold" if a read error occurs 
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0008 c36b00 
000b 



006b 15 
006c ca004a 



************************************************* 
* user supplied read operation goes here.., 

it 

; remove this when patche 



jmp 
ds 



past$patch 
60h 



past$patch: 

; go to next sector if load is incomplete 

dcr d ; sects=sects-l 

jz boot ; head for the bios 

more sectors to load 



we aren't using a stacks so use <sp> as scratch registe 
to hold the load address increment 



006£ 318000 
0072 39 


Ixi 
dad 


sp,128 
sp 


0073 0c 

0074 79 

0075 felb 
0077 da0800 


inr 
mov 
cpi 
jc 


c 

a,c 
27 
Isect 


; 


end of track. 


increm 


007a 0e01 
007c 04 
007d C30800 
0080 


mvi 
inr 
jmp 
end 


c,l 

b 

Isect 



; 128 bytes per sector 

; <hl> = <hl> + 128 

; sector = sector + 1 

; last sector of track? 

; no, go read another 



sector = 1 
track = track + 1 
for another group 
of boot loader 
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APPENDIX F: CP/M DISK DEFINITION LIBRARY 

l! ? CP/M 2.0 disk re-detinition library 

3: ; copyright (c) 1979 

4: ; Digital Rijfcearch 

5: ; Box 579 

6: ; Pacific Grove, CA 

7: ; 93950 

8: ; 

9: ? CP/M logical disk drives are defined using the 

l<*s ; macros given below r where the sequence of calls 

11: ; is: 
12: ; 

13: ; disks a 

14: ; diskdef oarameter-list-0 

15: ; diskdef oarameter-list-l 
16: ; 

17: ; diskdef oarameter-list-n 

18: ; endef 
19: ; 

20: ; where n is the number of logical disk drives attached 

21: ; to the CP/M system, and oarameter-list-i defines the 

22: ; characteristics of the ith drive (i=0 ,lr . • . ^n-l) 
23: ; 

24: ; each pararaeter-list-i takes the form 
25: ; dn,f sc,lsc, [skf 1 ,bls,Qks,dir ,cks,of s, [0] 

26: ; where 

27: ; dn is the disk number 0,1,.,., n-1 

28: ; fsc is tae first sector number (usually or 1) 

29: ; Isc is tae last sector number on a track 

30: ; skf is Ofcitional "skew factor" for sector translate 

31: ; bis is tne data block size (1024,2048, ... ,16384) 

32: ; dks is tnt disk size in bis increments (word) 

33: ; dir is tnt number of directory elements (word) 

34: ; cks is the number of dir elements to checksum 

35: ; ofs is the number of tracks to skip (word) 

36: ; [0] is an optional which forces 16K/directory en 
37: ? 

38: ; for convenience, the form 
39: ; dn,dra 

40: ; defines disk dn as having the same characteristics as 

41: ; a previously defined disk dm. 
42: ; 

43: ; a standard four drive CP/M system is defined by 
44: ; disks 4 

45: ; diskdef 0,1,26,6,1024,243,64,64,2 

46: ; dsk set 
47: ; rept 3 

48: ; dsk set dsk+1 
49: ; diskdef %dsk,0 

50: ; endm 

51: ; endef 

52: ; 

53: ; the value of "begdat" at the end of assembly defines t 
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beginning of the uninitialize ram area above the bios, 
while the value of "enddat" defines the next location 
following the end of the data area, the size of this 
area is given by the value of "datsiz" at the end of t 
assembly, note that the allocation vector will be qui 
large if a large disk size is defined with a small bio 
size. 



dskhdr 
dpe&dn: 



macro dn 

define a single disk header list 



dw 
dw 
dw 
dw 

endm 



xlt&dn,0000h 
0000h,0000h 
dirbuf ,dpb&dn 
csv&dn,aiv&dn 



; translate table 
;scratch area 
;dir buff^parm block 
;checkr alloc vectors 



disks 

• • 

ndisks 
dpbase 

dsknxt 
dsknxt 



macro nd 

define nd disks 

set nd ;;for later reference 

equ $ ;base of disk parameter blocks 

generate the nd elements 

set 

rept nd 

dskhdr %dsknxt 

set dsknxc-i-l 

endm 

endm 



dpbhdr 
dpb&dn 



macro 

equ 

endm 



dn 
§ 



;disk parm block 



ddb macro data, comment 
; ; define a db statement 

db data 

endm 



comment 



ddw 

7 f 



macro data, comment 
define a dw statement 
dw data 
endm 



comment 



gcd 



gcdm 
gcdn 
gcdr 

gcdx 
gcdr 



macro m,n 

greatest common divisor of m,n 

produces value gcdn as result 

(used in sector translate table generation) 



set 

set 

set 

rept 

set 

set 

if 

exitm 

endif 



m 

n 



65535 

gcdm/gcdn 

gcdm - gcdx*gcdn 

gcdr = 



; ;variable for m 



; ;variable for n 
; ;variable for r 
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109: 

1101 

111: 
112: 
113: 
114: 
115: 
116: 
117: 
118j 
119: 
120: 
121: 
122: 
123: 
124: 
125: 
126: 
127: 
12t3: 
129; 
130: 
131: 
132: 
133: 
134: 
135: 
136: 
137: 
138: 
139: 
140: 
141: 
142: 
143: 
144: 
145: 
146: 
147: 
148: 
149: 
150: 
151: 
152: 
153: 
154: 
155: 
156: 
157: 
158: 
159: 
160: 
161: 
162: 
163: 



gcdm 
gcdn 



set 
set 
endm 
endm 



gcdn 
gcdr 



diskdef macro dn,fsc,lsc,skf ,bls,dks,dir,cks,of s,kl6 
generate the set statements for later tables 
if nul Isc 
current disk dn same as orevious fsc 



dpb&dn 
ais&dn 
css&dn 
xlt&dn 

secmax 

sectors 

als&dn 

als&dn 

css&dn 

bikval 
blkshf 
blkmsk 



blkshf 
blkmsk 
bikval 



1 1 

bikval 
extmsk 



f 9 

extmsk 
Dlkval 



extmsk 

extmsk 
dirrem 



dpb&fsc ;3cruivalent parameters 
als&fsc ;same allocation vector size 
css&fsc ;same checksum vector size 
xltSrfsc ;same translate table 

Isc-(fsc) ;;sectors 0... secmax 
secmax+1; ; number of sectors 
(dks)/8 ;;size of allocation vector 
( (dks) mod 5) ne 
als&dn+l 

(cks)/4 ;;number of checksum elements 



equ 

equ 

equ 

equ 

else 

set 

set 

set 

if 

set 

endif 

set 

generate the block shift value 



bls/128 





16 

blkval=l 



;number of sectors/block 
?counts right 0*s in bikval 
;iills with l*s from right 
;once for each bit position 



set 

set 

set 

rept 

if* 

exitm 

endif 

otherwise^ high order 1 not found yet 

set blkshf+1 

set (blkmsk shl 1) or 1 

set blkval/2 

endm 

generate the extent mask byte 



bls/1024 ;;number of kilobytes/block 

;;fiil from right with I's 

16 

blkval=l 



set 

set 

rept 

if 

exitm 

endif 

otherwise more to shift 

set (extmsk shl 1) or 1 

set blkval/2 

endm 

may be double byte allocation 

if (dks) > 256 

set (extmsk shr 1) 

endif 

may be optional [0] in last position 

if not nul kl6 

set kl6 

endif 

now generate directory reservation bit vector 

set dir ;;# remaining to process 
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164: 


dirbks 


set 


bls/32 ;;nUiTiber of entries per block 


165: 


dirblk 


set 


;;fill with I's on each loop 


166: 




rept 


16 


167: 




if 


dirrem=0 


168: 




exitm 




169: 




endif 




170: 


; ; 


not complete, iterate once again 


171: 


• • 

# 9 


shift r 


ight and add 1 high order bit 


172: 


dirblk 


set 


(dirblk shr i) or B000h 


173: 




if 


dirrem > dirbks 


174: 


dirrem 


set 


dirrem-dirbks 


175: 




else 




176: 


dirrem 


set 





177: 




endif 




178: 




endm 




179: 




dpbhdr 


dn ; jganerate equ $ 


180: 




ddw 


%sectors,<?sec per track> 


181: 




ddb 


%blkshf,<;blcck shift> 


182: 




ddb 


%blkmsk,<;blcck mask> 


183: 




ddb 


%extmsk,<;extnt mask> 


184: 




ddw 


%(dks)-l,<;aisk size-l> 


185! 




udw 


% (dir)-l ,<;airectorY max> 


186: 




odb 


%dirblk shr 8,<;alloc0> 


187: 




ddb 


%dirblk ana 0f fh,<;allocl> 


188: 




ddw 


%(cks)/4,<;check size> 


189: 




ddw 


%ofs,<;of fset> 


190: 


; ; 


generate the translate table, if requested 


191; 




if 


nul skf 


192: 


xlt&dn 


equ 


;no xlate taole 


193; 




else 




194i 




if 


skf = 


195 


: xlt&dn 


equ 


;no xlate table 


196 




else 




197 


: ; ; 


generate the translate taole 


198 


: nxtsec 


set 


;;iiext sector to fill 


199 


: nxtbas 


set 


;;mcves by one on overflow 


200 




gcd 


%sectors,skf 


201 


• • • 

• 9 9 


gcdn = 


gcd(sectors,skew) 


202 


: neltst 


set 


sectors/gcdn 


203 


: ; ; 


neltst 


is number of elements to generate 


204 


: ; ; 


before 


we overlap oievious elements 


205 


: nelts 


set 


neltst ;;counter 


206 


: xlt&dn 


equ 


$ ; translate table 


207 




rept 


sectors ; yonce for each sector 


208 




if 


sectors < 256 


209 




ddb 


%nxtsec+(fsc) 


210 




else 




211 




ddw 


%nxtsec+(fsc) 


212 




endif 




213 


I nxtsec 


set 


nxtsec+(skf ) 


214 




if 


nxtsec >= sectors 


215 


: nxtsec 


set 


nxtsec-sectors 


216 




endif 




217 


• nelts 


set 


nelts-1 


218 




if 


nelts = 
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219 


: nxtbas 


. set 


nxtbas+i 


220 


: nxtsec 


set 


nxtbas 


221 


: nelts 


set 


neltst 


222 




endif 




223 




endm 




224 




endif 


; ;end of nul fac test 


225 




endif 


; ;end of nul bis test 


226 




endm 




227 


! ; 






228: 


: defds 


macro 


lab, space 


229: 


lab: 


ds 


space 


230: 




endm 




231: 


; 






232: 


Ids 


macro 


Ib^dn^val 


233: 




defds 


lb&dn,%val&dn 


234: 




endm 




235: 


; 






236: 


endet 


macro 




237: 


; ; 


generate the necessary ram data area 


238: 


begdat 


equ 


$ 


239: 


ditouf : 


ds 


128 ;directory access bu 


240: 


dsknxt 


set 





241: 




rept 


ndisks ; ;once for eacn disk 


242: 




Ids 


alv,%dsknxt,als 


243: 




Ids 


csv,%dsknxt,css 


244: 


dsknxt 


set 


dsknxt+1 


245: 




endm 




246: 


enddat 


equ 


$ 


247: 


datsiz 


equ 


$-begdat 


248: 


• • 


db at 


this point forces hex record 


249: 




endm 
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APPENDIX G: BLOCKING AND DEBLOCKING ALGORITHMS. 



1; 
2: 
3: 
4: 
5: 
6: 
7; 
8: 
9; 
10: 
11: 
12: 
13: 
14: 
15: 
16: 
17: 
18; 
19: 
2( 
21: 
22: 
23: 
24: 
25: 
26: 
27: 
28: 
29: 
30: 
31: 
32: 
33: 
34: 
35: 
36: 
37: 
38: 
39: 
40: 
41: 
42: 
43: 
44: 
45: 
46: 
47: 
48: 
49: 
50: 
51: 
52: 
53: 



f 9 
t } 

@X 



***************************************************** 

* * 

* Sector Deblocking Algorithms for CP/M 2.0 * 

* * 

utility macro to compute sector mask 

smask macro hblk 

compute log2(hblk)r return @x as result 

(2 ** @x = hblk on return) 

set hblk 

set 

;; count right shifts of @y until = 1 

rept 8 

if @y = 1 

exitm 

endif 

;; 3y is not 1, shift right one position 

@y set @y shr 1 

@x set @x + 1 

endm 

enom 



* it 

* CP/M to host disk constants * 

* * 

blksiz equ 2048 ;CP/M allocation size 

512 ;host disk sector size 

20 ;host disk sectors/trk 

hstsiz/128 ;CP/M sects/host buff 

hstblk * hstspt ;CP/M sectors/track 

hstblk-1 ; sector mask 

hstblk ;compute sector mask 

ex ;log2 (hstblk) 



hstsiz equ 

hstspt equ 

hstblk equ 

cpmspt equ 

secmsk equ 

smask 

secshf equ 



* * 

* BDOS constants on entry to write * 

* * 

*******************ifc******************4r***** ********* 

wrall equ ;write to allocated 



wrdir 
wrual 



equ 
equ 
equ 



;write to directory 
;write to unallocated 



*****************************4lr*********************** 

* * 

* The BDOS entry points given below show the * 

* code which is relevant to deblocking only. * 

* * 
***************************************************** 
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54: 
55i 
56: 
57: 
58: 
59: 
60: 
61: 
62: 
63: 
64: 
65: 
66: 
67: 
68: 
69: 
70: 
71: 
72: 
73: 
74: 
75: 
76: 
77: 
78: 
79: 
80: 
81: 
82: 
83: 
84: 
85: 
86: 
87: 
86: 
89: 
90: 
91: 
92: 
93: 
94: 
95: 
96: 
97: 
98: 
99: 
100: 
101: 
102: 
103: 



dpbase 

t 

boot: 
wboot; 



seldsk: 



settrk: 



setsec; 



setdma: 



DISKDEF macro, or hand coded tables go here 
equ $ ;disk param block base 



;enter here on system boot to initialize 
xra a ;0 to accumulator 

sta hstact ;host buffer inactive 

sta unacnt ;clear unalloc count 

ret 



;select disk 



mov 

sta 

mov 

mvi 

rept 

dad 

endm 

Ixi 

dad 

ret 



a,c 

sekdsk 

l,a 

h,0 

4 

h 

d, dpbase 
d 



;selected disk number 
;seek disk number 
;disk number to HL 

; multiply by 16 



;base of parm block 
;hl=.dpb(curdsk) 



;set track given by registers BC 

mov h,b 

mov l,c 

shld sektrk ; track to seek 

ret 



;set sector given by register c 

mov a,c 

sta seksec ; sector to seek 

ret 



;set dma address given by BC 

mov h^b 

mov l,c 

shld dmaadr 

ret 



sectran: 



; translate sector number BC 
mov h,b 
mov lyC 
ret 
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104: 
105: 
106: 
107: 
108: 
109: 
110: 
111: 
112: 
113: 
114; 
115: 
116: 

117! 
118! 
119! 

120: 
121: 
122: 
123: 
124: 
125: 
126: 
127: 
128: 
129: 
130: 
131: 
132: 
133: 
134: 
135: 
136: 
137: 
138: 
139: 
140: 
141: 
142: 
143: 
144: 
145: 
146: 
147: 
148: 
149: 
150: 
151: 
152: 
153: 
154: 
155: 
156: 
157: 
158: 



* * 

* The READ entry point takes the place of * 

* the previous BIOS defintion for READ, * 

* * * 
*******************************i^** ******************* 

read: 

;read the selected CP/M sector 

mvi a^l 

sta readop ;read operation 

sta rsflag ;must read data 

mvi arwrual 

sta wrtype ; treat as unalloc 

jinp rwoper ;to perform the read 

***************************************************** 

* * 

* The WRITE entry point takes the place of * 

* the previous BIOS defintion for WRITE, * 

* * 
***************************************************** 

write: 

;write the selected CP/M sector 

xra a ;0 to accumulator 

sta readop ;not a read operation 

mov a,c ;write type in c 

sta wrtype 

cpi wrual ;write unallocated? 

jnz chkuna ;check for unalloc 

; write to unallocated^ set parameters 

;next unalloc recs 

;disk to seek 
;unadsk = sekdsk 

;unatrk = sectrk 

;unasec = seksec 



mvi 


a,blksi2/128 


sta 


unacnt 


Ida 


sekdsk 


sta 


unadsk 


Ihld 


sektrk 


shld 


unatrk 


Ida 


seksec 


sta 


unasec 



chkuna: 



;check for write to unallocated sector 

Ida unacnt ;any unalloc remain? 

ora a 

jz alloc ;skiD if not 

more unallocated records remain 

dcr a ?unacnt = unacnt-1 

sta unacnt 

Ida sekdsk ;same disk? 

Ixi h, unadsk 

cmp m ? sekdsk = unadsk? 

jnz alloc ;skip if not 

disks are the same 
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159: 
160: 
161: 
162: 
163: 
164: 
165: 
166: 
167: 
168: 
169: 
170: 
171: 
172: 
173: 
174: 
175: 
176: 
177: 
178: 
179: 
180: 
181: 
182: 
183: 
184: 
185: 
186: 
187: 
188: 
189: 
190: 
191; 
192: 
193: 
194: 
195: 
196: 
197: 
198; 
199: 
200: 
201: 
202: 
203: 
204: 
205: 
206: 
207: 
208: 
209: 
210: 
211: 
212: 
213: 



Ixi 

call 

jnz 


h,unatrk 

sektrkcmp 

alloc 


tracks 
Ida 


are the same 
seksec 


Ixi 


h,unasec 


cmp 
jnz 


m 
alloc 


match r 


move to next se 


inr 


m 


mov 


a,m 


cpi 


cpmspt 
noovf 


overflow to next track 


mvi 
Ihld 


m,0 
unatrk 


inx 
shld 


h 
unatrk 



noovf: 



;sektrk = unatrk? 
;skip if not 



;same sector? 

; seksec = unasec? 
;skip if not 



; unasec = unasec+1 
;end of track? 
;count CP/M sectors 
;skip if no overflow 



; unasec = 
?unatrk = unatrk+1 



;match found, mark as unnecessary read 

xra a ;0 to accumulator 

sta rsflag ;rsflag = 

jmp rwoper ;to perform the write 



alloc: 



xra 


a 


sta 


unacnt 


inr 


a 


sta 


rsflag 



;not an unallocated record, requires pre-read 

to accum 
unacnt = 

1 to accum 
rsflag = 1 

**:Ar **********************#****************** ********* 

* * 

* Common code for READ and WRITE follows * 

* * 
***************************************************** 

rwoper: 

;enter here to perform the read/write 

;zero to accum 
;no errors (yet) 
;compute host sector 

;carry = 
; shift right 

;host sector to seek 



xra 


a 


sta 


erflag 


Ida 


seksec 


rept 


secshf 


or a 


a 


rar 




endm 




sta 


sekhst 



active host sector? 
Ixi hrhstact 
mov a,m 
mvi m,l 



;host active flag 
; always becomes 1 



210 



214: 




ora 


a ;was it already? 


215: 




jz 


filhst ;fill host if not 


216: 


f 






217: 


; 


host 


buffer active, same as seek buffer? 


218: 




Ida 


sekdsk 


219: 




Ixi 


h,hstdsk ;same disk? 


220: 




cmp 


m ; sekdsk = hstdsk? 


221: 




jnz 


nomatch 


222: 


; 






223: 


', 


same 


disk, same track? 


224: 




Ixi 


h,hsttrk 


225: 




call 


sektrkcmp jsektrk = hsttrk? 


226: 




jnz 


nomatch 


227: 


i 






228: 


• 
t 


same 


disk, same track, same buffer? 


229: 




Ida 


sekhst 


230: 




Ixi 


h,hstsec ; sekhst « hstsec? 


231: 




cmp 


m 


232i 




jz 


match ;skip if match 


233: 


; 






234i 


. nomatch 


: 




235i 




yproper disk, but not correct sector 


236: 




Ida 


hstwrt ;host written? 


237! 




ora 


a 


238: 




cnz 


writehst ; clear host buff 


239: 


! ; 






240! 


! filhst: 






24l! 




;may 


have to fill the host buffer 


242! 




Ida 


sekdsk 


243 




sta 


hstdsk 


244 




Ihld 


sektrk 


245 




shld 


hsttrk 


246 




Ida 


sekhst 


247 




sta 


hstsec 


248 




Ida 


rsflag ;need to read? 


249 




ora 


a 


250 




cnz 


readhst ;yes, if 1 


251 




xra 


a ;0 to accum 


252 




sta 


hstwrt ;no pending write 


253 


: ; 






254 


: match: 






255 




• copy data to or from buffer 


256 




Ida 


seksec ;mask buffer number 


257 




ani 


secmsk ;least signif bits 


258 




mov 


l,a jready to shift 


259 




mvi 


h,0 ;double count 


260 




rept 


7 ;shift left 7 


261 




dad 


h 


262 




endm 




263 


: ; 


hi has relative host buffer address 


264 




Ixi 


d,hstbuf 


265 




dad 


d ;hl » host address 


266 




xchg 


;now in DE 


267 




Ihld 


dmaadr ;get/put CP/M data 


268 




mvi 


c,128 ; length of move 
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269: 

270: 

271: 

272: 

273i 

274: 

275: 

276: 

277: 

278; 

279: 

280: 

281i 

282: 

283: 

284: 

285: 

286: 

287: 

288: 

289: 

290; 

291: 

292: 

293: 

294: 

295: 

296: 

297i 

298: 

299; 

300: 

301: 

302: 

303: 

304: 

305: 

306; 

307: 

30 

309; 

310; 

311: 

312: 

313: 

314: 

315: 

316: 

317; 

318; 

319: 

320: 



Ida 


readop 


ora 


a 


jnz 


rwmove 



;which way? 
;skip if read 



write operation, mark and switch direction 

mvi a,l 

sta hstwrt ;hstwrt = 1 

xchg ;source/dest swap 



rwmove : 



;C initially 128, DE is source, HL is dest 

Idax d ; source character 

inx d 

mov m^a ;to dest 

inx h 

dcr c ?loop 128 times 

jnz rwmove 

data has been moved to/from host buffer 

Ida wrtype ; write type 

cpi wrdir ;to directory? 

Ida erf lag ;in case of errors 

rnz ;no further processing 



clear host buffer for directory write 

ora a ;errors? 

;skip if so 

a ;0 to accum 

hstwrt ;buffer written 

writehst 

erflag 



rnz 

xra 

sta 

call 

Ida 

ret 



***************************************************** 

* * 

* Utility subroutine for 16-bit compare * 

* * 
***************************************************** 

sektrkcmp: 

;HL = .unatrk or .hsttrk, compare with sektrk 

xchg 

Ixi h, sektrk 

Idax d ;low byte compare 

cmp m ;same? 

rnz ;return if not 

; low bytes equal, test high Is 

inx d 

inx h 

Idax d 

cmp m ;sets flags 

ret 
; 
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321: 
322: 
323: 
324: 
325: 
326: 
327! 
328: 
329i 
330: 
331: 
332: 
333: 
334: 
335: 
336: 
337: 
338: 
339: 
340: 
341: 
342: 
343: 
344: 
345: 
346: 
347: 
348: 
349: 
350: 
35l! 
352: 
353: 
354: 
355: 
356: 
357: 
358: 
359: 
360: 
361: 
362: 
363: 
364: 
365: 
366: 
367: 
368: 
369: 
370: 



*************ifc************ilr*****ir*4rilr***************** 



WRITEHST performs the physical write to * 
the host disk, READHST reads the physical * 
disk. * 

* 

writehst: 

;hstdsk = host disk #, hsttrk = host track #, 
;hstsec = host sect #. write "hstsiz** bytes 
;from hstbuf and return error flag in erflag, 
;return erflag non-zero if error 
ret 

7 

readhst: 

;hstdsk = host disk #, hsttrk = host track #, 
;hstsec = host sect #. read "hstsiz" bytes 
;into hstbuf and return error flag in erflag. 
ret 

* * 

* Unitialized RAM data areas * 

* * 
***************************************************** 



sekdsk: ds 

sektrk: ds 

seksec: ds 
? 

hstdsk: ds 

hsttrk: ds 

hstsec: ds 

sekhst: ds 

hstact: ds 

hstwrt: ds 

• 

unacnt: ds 

unadsk: ds 

unatrk: ds 

unasec: ds 

erflag: ds 

rsflag: ds 

readop: ds 

wrtype: ds 

dmaadr: ds 

hstbuf: ds 



hstsiz 



;seek disk number 
;seek track number 
;seek sector number 

;host disk number 
;host track number 
;host sector number 

;seek shr secshf 
;host active flag 
;host written flag 

;unalloc rec cnt 
;last unalloc disk 
?last unalloc track 
;last unalloc sector 

;error reporting 
yread sector flag 
;1 if read operation 
;write operation type 
;last dma address 
;host buffer 
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371: 'ii**************************************************** 

372: I* * 

373: ;* The ENDEF macro invocation goes here * 

374: ;* * 

375. .********«***************************«**************** 

376: ' end 
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